GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  POD::AUTOPOD (3)

.ds Aq ’

NAME

Pod::Autopod - Generates pod documentation by analysing perl modules.

CONTENTS

SYNOPSIS



 use Pod::Autopod;

 new Pod::Autopod(readfile=>Foo.pm, writefile=>Foo2.pm);

 # reading Foo.pm and writing Foo2.pm but with pod


 my $ap = new Pod::Autopod(readfile=>Foo.pm);
 print $ap->getPod();

 # reading and Foo.pm and prints the generated pod.

 my $ap = new Pod::Autopod();
 $ap->setPerlCode($mycode);
 print $ap->getPod();
 $ap->writeFile(out.pod);

 # asumes perl code in $mycoce and prints out the pod.
 # also writes to the file out.pod



DESCRIPTION

This Module is designed to generate pod documentation of a perl class by analysing its code. The idea is to have something similar like javadoc. So it uses also comments written directly obove the method definitions. It is designed to asumes a pm file which represents a class.

Of course it can not understand every kind of syntax, parameters, etc. But the plan is to improve this library in the future to understand more and more automatically.

Please note, there is also an autopod command line util in this package.

REQUIRES

Pod::Autopod

Pod::Abstract::BuildNode

Pod::Abstract

FileHandle

HOWTO

To add a documentation about a method, write it with a classical remark char # before the sub{} definition:



 # This method is doing foo.
 #
 #  print $self->foo();
 #
 #
 # It is not doing bar, only foo.
 sub foo{
   ...
 }



A gap before sub{} is allowed.

In further versions of autopod, here new features will appear.

To define parameters and return values you can use a boundle of keywords. So far parameters and return values can not realy be autodetected, so manual way is necessary, but it is designed to type it rapidly.



 sub foo{ # void ($text)
  ...
 }



The example above produces the following method description:



 $self->foo($text);



The object $self is the default and automatially used when a constructor was found (new) or the class inherits with ISA or use base. You can change this by the parameter selfstring in the autopod constructor.

The example looks simple, but the engine does more than you think. Please have a look here:



 sub foo{ # void (scalar text)
  ...
 }



That procudes the same output! It means the dollar sign of the first example is a symbol which means scalar.



 sub foo{ # ($)
  ...
 }



Produces:



 $self->foo($scalar);



As you see, that was the quickest way to write the definition. The keywork void is default.

The following keywords or characters are allowed:



 array       @
 arrayref   \@
 hash        %
 hashref    \%
 method      &
 scalar      $
 scalarref  \$
 void       only as return value



Now a more complex example:



 sub foo{# $state ($firstname,$lastname,\%persondata)
 ...
 }



produces:



 my $state = $self->foo($firstname, $lastname, \%persondata);



or write it in java style:



 sub foo{# scalar state (scalar firstname,scalar lastname,hashref persondata)
 ...
 }



Multiple return values may be displayed as following:



 sub foo{# $a,$b ($text)
 ...
 }



produces:



 my ($a, $b) = $self->foo($text);



If you want to use key values pairs as in a hash, you may describe it like:



 sub foo{# void (firstname=>$scalar,lastname=>scalar)
 ...
 }



The second scalar above is without a $, that is no mistake, both works.

There is also a way to expain that a value A OR B is expected. See here:



 sub foo{# $lista|\$refb (\@list|$text,$flag)
 ...
 }



procudes:



  my $lista | \$refb = $self->foo(\@list | $text, $flag);



Of course, that is not an official perl syntax with the or |, but it shows you that is expected.

In the First Part obove all method descriptions, you can add general informations, which are per default displayed under the head item DESCRIPTION. But also own items can be used by underlining a text with = chars like:



 # HOWTO
 # =====
 # Read here howto do it.



Some of these title keywords are allways places in a special order, which you can not change. For example LICENSE is allways near the end.

METHODS

    new



 my $object = $self->new($filename => $scalar, alsohiddenmethods => $scalar, selfstring => $scalar);



ConstructorThe keyvalues are not mandatory.selfstring may hold something like ’$self’ as alternative to ’$self’, which is default.alsohiddenmethods gets a boolean flag to show also methods which starts with _.

    buildPod



 $self->buildPod();



Builds the pod. Called automatically when imporing a perl code.

    getBorderString



 my $scalar = $self->getBorderString();



Returns the border string which delimit the perl code and pod inside a pm file.

    getPerlCode



 my $text = $self->getPerlCode();



Returns perl code which was set before.

    getPod



 my $text = $self->getPod();



Returns the pod formated text.s

    readDirectory



 $self->readDirectory($directory, updateonly => $scalar, pod => $scalar, verbose => $scalar);



scans a directoy recoursively for pm files and maygenerate pod of them.You can also set the flag updateonly to build new podonly for files you already build a pod (inside the file)in the past. Alternatively you can write the magic wordAUTOPODME somewhere in the pm file what signals that thispm file wants to be pod’ed by autopod.The flag pod let will build a separate file. If poddir set,the generated pod file will be saved to a deparate directory.With verbose it prints the list of written files.

    readFile



 $self->readFile($filename);



Reading a Perl class file and loads it to memory.

    scanArray



 $self->scanArray();



This class may scan the perl code.But it is called automatically when importing a perl code.

    setBorderString



 $self->setBorderString($borderstring);



Set an alternative border string.If you change this, you have to do it again when updating the pod.

    setPerlCode



 $self->setPerlCode($text | \@array);



Expects Perl code as arrayrefor text (scalar).When used, it automatically runs scanArray().

    writeFile



 $self->writeFile($filename);



writes a pod fileIf the file has a pm extension, it writes the perl code and the podIf the file has a pod extension or any, it only writes the pod.

AUTHOR

Andreas Hernitscheck ahernit(AT)cpan.org

LICENSE

You can redistribute it and/or modify it under the conditions of LGPL.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 POD::AUTOPOD (3) 2014-09-29

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.