NAME

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

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

Data::Dumper

Pod::Abstract::BuildNode

Pod::Abstract

FileHandle

5.006 Pod::Abstract uses features of 5.6

HOWTO

 # 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.

Added some hacks to teach this tool also some doxygen parametes. For example:

 # @brief  kept as simple text
 # @param  text to be added
 # @return string with some text
 sub foo{
   return "abc".shift;
 }

procudes:

  my $string = $self->foo($text);

METHODS

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

 $self->buildPod();

 $self->foo();

 print $self->foo();

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

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

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

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

 $self->readFile($filename);

 $self->scanArray();

 $self->setBorderString($borderstring);

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

 $self->writeFile($filename);

AUTHOR

LICENSE

By the way, the source code is quite bad. So feel free to replace this idea with something better Perl OO code.