NAME
POD::Generate - programmatically generate plain old documentation
VERSION
v0.02
SYNOPSIS
use POD::Generate;
my $pg = POD::Generate->new();
my $data = $pg->start("Test::Memory")
->synopsis(qq|This is a code snippet.\n\n\tuse Test::Memory;\n\n\tmy \$memory = Test::Memory->new();|)
->description(q|A test of ones memory.|)
->methods
->h2("Mind", "The element of a person that enables them to be aware of the world and their experiences, to think, and to feel; the faculty of consciousness and thought.")
->v(q| $memory->Mind();|)
->h3("Intelligence", "A person or being with the ability to acquire and apply knowledge and skills.")
->v(q| $memory->Mind->Intelligence();|)
->h4("Factual", "Concerned with what is actually the case.")
->v(q| $memory->Mind->Intelligence->Factual(%params);|)
->item("one", "Oxford, Ticehurst and Potters Bar.")
->item("two", "Koh Chang, Zakynthos and Barbados.")
->item("three", "An event or occurrence which leaves an impression on someone.")
->footer(
name => "LNATION",
email => 'email@lnation.org'
)
->end("string");produces...
=head1 NAME
Test::Memory
=cut
=head1 SYNOPSIS
This is a code snippet.
use Test::Memory;
my $memory = Test::Memory->new();
=cut
=head1 DESCRIPTION
A test of ones memory.
=cut
=head1 METHODS
=cut
=head2 Mind
The element of a person that enables them to be aware of the world and their experiences, to think,
and to feel; the faculty of consciousness and thought.
$memory->Mind();
=cut
=head3 Intelligence
A person or being with the ability to acquire and apply knowledge and skills.
$memory->Mind->Intelligence();
=cut
=head4 Factual
Concerned with what is actually the case.
$memory->Mind->Intelligence->Factual(%params);
=over
=item one
Oxford, Ticehurst and Potters Bar.
=item two
Koh Chang, Zakynthos and Barbados.
=item three
An event or occurrence which leaves an impression on someone.
=back
=cut
=head1 AUTHOR
LNATION, C<< <email at lnation.org> >>
=cut
=head1 BUGS
Please report any bugs or feature requests to C<bug-test-memory at rt.cpan.org>, or through
the web interface at L<https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Memory>. I will
be notified, and then you'll automatically be notified of progress on your bug as I make changes.
=cut
=head1 SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Test::Memory
You can also look for information at:
=over
=item * RT: CPAN's request tracker (report bugs here)
L<https://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Memory
=item * Search CPAN
L<https://metacpan.org/release/Test-Memory>
=back
=cut
=head1 ACKNOWLEDGEMENTS
=cut
=head1 LICENSE AND COPYRIGHT
This software is Copyright (c) 2022 LNATION
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)
=cut
=cutDESCRIPTION
This module purpose is to assist with programmatically generating plain old documentation from code.
METHODS
new
Instantiate a new POD::Generate object. This accepts the following parameters most of which are callbacks which are called when you set a specific plain old document command/identifier.
POD::Generate->new(
pod => [ ... ],
p_cb => sub { ... },
h1_cb => sub { ... },
h2_cb => sub { ... },
h3_cb => sub { ... },
h4_cb => sub { ... },
item_cb => sub { ... },
version_cb => sub { ... },
description_cb => sub { ... },
synopsis_cb => sub { ... },
methods_cb => sub { ... },
exports_cb => sub { ... },
author_cb => sub { ... },
bugs_cb => sub { ... },
support_cb => sub { ... },
acknowledgements_cb => sub { ... },
license_cb => sub { ... }
);pod
An existing internal pod struct which can either be a hash reference if it's the parent object or an array ref if it is a child object which relates to a specific single package.
p_cb
A callback called each time the p method is called, it should be used to manipulate the data which is added to the pod array.
h1_cb
A callback called each time the h1 method is called, it should be used to manipulate the data which is added to the pod array.
h2_cb
A callback called each time the h2 method is called, it should be used to manipulate the data which is added to the pod array.
h3_cb
A callback called each time the h3 method is called, it should be used to manipulate the data which is added to the pod array.
h4_cb
A callback called each time the h4 method is called, it should be used to manipulate the data which is added to the pod array.
item_cb
A callback called each time the item method is called, it should be used to manipulate the data which is added to the pod array.
versioncb
A callback triggered each time the version method is called, it should be used to manipulate the data which is added to the pod array.
description_cb
A callback triggered each time the description method is called, it should be used to manipulate the data which is added to the pod array.
synopsis_cb
A callback triggered each time the synopsis method is called, it should be used to manipulate the data which is added to the pod array.
methods_cb
A callback triggered each time the methods method is called, it should be used to manipulate the data which is added to the pod array.
exports_cb
A callback triggered each time the exports method is called, it should be used to manipulate the data which is added to the pod array.
author_cb
A callback triggered each time the author method is called, it should be used to manipulate the data which is added to the pod array.
bugs_cb
A callback triggered each time the bugs method is called, it should be used to manipulate the data which is added to the pod array.
support_cb
A callback triggered each time the support method is called, it should be used to manipulate the data which is added to the pod array.
support_items_cb
A callback triggered each time the support method is called, it should be used to manipulate the data which is added to the pod array.
acknowledgements_cb
A callback triggered each time the acknowledgements method is called, it should be used to manipulate the data which is added to the pod array.
license_cb
A callback triggered each time the license method is called, it should be used to manipulate the data which is added to the pod array.
pod
A reference to the internal pod struct which can either be a hash reference if it's the parent object or an array reference if it is a child object which relates to a specific single package.
$pg->pod;start
Start documentation for a new module/package/thing, it is equivalent to calling the ->name. method.
$pg->start($name, $abbr);end
End the documentation for a new module/package/thing, it is equivalent to calling the ->generate method.
$pg->end($type);name
Start documentation for a new module/package/thing, name accepts two parameteres a name of the thing and an summary of what the thing does. The summary is prepended to the name in the NAME section of the plain old documentation.
$pg->name($module, $summary)generate
End documentation for a new module/package/thing, generate accepts a single param which is the type of generation you would like. Currently there are three options they are string, file and seperate_file.
$pg->generate($type)add
This is a generic method to add a new section to the POD array, many of the following methods are just wrappers around this add method. It accepts three parameters the identifier/command, the title for the section and the content. All params are optional and undefs can be passed if that is what you desire to do.
$pg->add($identifier, $title, $content)p
Add a new paragraph to the current section, this method will format the text to be fixed width of 100 characters.
$pg->p($content)v
Add a new verbose paragraph to the current section, this method does not format the width of the content input so will render as passed.
$pg->v($content)h1
Add a new head1 section.
$pg->h1($title, $content)h2
Add a new head2 section.
$pg->h2($title, $content)h3
Add a new head3 section.
$pg->h3($title, $content)h4
Add a new head4 section.
$pg->h4($title, $content)item
Add a new item section, this will automatically add the over and back identifiers/commands.
$pg->item($title, $content)version
Add a new head1 VERSION section.
$pg->version($content)description
Add a new head1 DESCRIPTION section.
$pg->item($content)synopsis
Add a new head1 SYNOPSIS section.
$pg->synopsis($content)methods
Add a new head1 METHODS section.
$pg->methods($content)exports
Add a new head1 EXPORTS section.
$pg->exports($content)footer
Add the footer to a module/packages POD, this will call formatted_author, bugs, support, acknowledgements and license in that order using there default values or values set in callbacks.
$pg->footer(
name => "LNATION",
email => "email\@lnation.org",
bugs => "...",
support => "...",
support_items => "...",
acknowledgements => "...",
license => "...",
);author
Add a new head1 AUTHOR section.
$pg->author($content)formatted_author
Add a new head1 AUTHOR section, this accepts two parameters the authors name and the authors email.
$pg->author($author_name, $author_email)bugs
Add a new head1 BUGS section.
$pg->bugs($content)support
Add a new head1 SUPPORT section.
$pg->support($content)acknowledgements
Add a new head1 ACKNOWLEDGEMENTS section.
$pg->acknowledgements($content)license
Add a new head1 LICENSE section.
$pg->license($content)to_string
Generate the current plain old documentation using what is stored in the pod attribute and return it as a string.
$pg->to_string()to_file
Generate the current plain old documentation using what is stored in the pod attribute and write it to the end of the modules file. The module must have an __END__ tag and anything which comes after will be re-written.
$pg->to_file()to_seperate_file
Generate the current plain old documentation using what is stored in the pod attribute and write it to a new .pod file for the given named module. Each run this file will be re-written.
$pg->to_seperate_file()AUTHOR
LNATION, <email at lnation.org>
BUGS
Please report any bugs or feature requests to bug-pod-generate at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=POD-Generate. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc POD::GenerateYou can also look for information at:
RT: CPAN's request tracker (report bugs here)
Search CPAN
ACKNOWLEDGEMENTS
LICENSE AND COPYRIGHT
This software is Copyright (c) 2022 LNATION
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)