/ 
Method-Signatures-WithDocumentation-0.001
River stage zero No dependents
/ Pod::Weaver::Section::AutoDoc

NAME

Pod::Weaver::Section::AutoDoc - Assemble documentation gathered from Sub::Documentation

VERSION

version 0.001

SYNOPSIS

Put

[AutoDoc]

into your weaver.ini.

DESCRIPTION

This module adds up to three new sections into your pod: METHODS, FUNCTIONS and "EXTENDS SECTION" in EXTENDS.

Any documentation gathered by Sub::Documentation will be assembled to an auto-generated pod for each method/function. Attribute definitions are not supported yet.

If the module extends some other module, and that module (or any module in the inheritance chain) uses Sub::Documentation, than the inherited methods will be included in the documentation.

SECTIONS

The sections will be added in this order to your pod at the desired position.

METHODS SECTION

To distinguish code objects as a class method, the param type should contain method. Only objects with that attribute are assembled in this section.

First, a pod command (head2) with the method name and a brief attribute list is printed. This maybe append with DEPRECATED.

Then these paragraphes are followed in this order:

  • A notice if the method was inherited from another module, with a link to it.

  • The purpose of the method.

  • The synopsis of the method, identified by example.

  • A list of all parameters with documentation (if available by identifier param)

  • All additional documentation identified by pod

  • The return value of the method, identified by returns

  • All throwables, identified by throws

  • A list, since when this method is available, identified by since

  • The deprecation warning, identified by deprecated

  • The list of all especially named authors, indentified by author

FUNCTIONS SECTION

To distinguish code objects as a class function, the param type should contain func. Only objects with that attribute are assembled in this section.

The rules to not differ from methods, so see there for a detailed description.

EXTENDS SECTION

Inserts a simple list of all parent classes with links to them.

FORMATTING TIPS

Multiline attributes (Purpose, Example, Pod, Returns, Throws, Deprecated and Param) are trimmed and re-indented by resetting all indentations to the first indentation with non-whitechars on the line. So, the following statement:

sub xxx :
    Pod(
        Lorem
          Ipsum
    )
{ ... }

results in:

=pod

Lorem
  Ipsum

=cut

But for the Example attribute, the verbatim block is automatically indented. Thus,

sub xxx :
    Example(
        my $xxx = xxx;
    )
{ ... }

results in:

=pod

        my $xxx = xxx;

=cut

The single-line attributes Since and Author should contain no line breaks.

For some readers it might be confusing the read a subroutine definition with many attributes. Theres is no best practise at the moment, but I suggest this template:

func foobar (Int $amount = 1) :
    Purpose(
        Prints out I<foo> and I<bar>
    )
    Example(
        foobar(2); # prints two foos and two bars
    )
    Param(
        $amount: how many foo and bar should be printed
    )
    Pod(
        This function is an example to show you a fancy way for its documentation
    )
    Returns(
        True on success
    )
    Throws(
        An error message if there is no output device
    )
    Since(
        1.000
    )
    Deprecated(
        Use L</foobar_v2> instead.
    )
    Author(
        John Doe
    )
{ ... }

The resulting pod looks like:

=head2 foobar ([ Int $amount ]) B<DEPRECATED>

Prints out I<foo> and I<bar>

B<Synopsis:>

        foobar(2); # prints two foos and two bars

B<Parameters:>

=over 4

=item * Int C<<< $amount >>> (optional, defaults to C<<<  1 >>>)

how many foo and bar should be printed

=back

This function is an example to show you a fancy way for its documentation

B<Returns:>

True on success

B<Throws:>

=over 4

=item * An error message if there is no output device

=back

B<Available since:> 1.000

B<DEPRECATION WARNING:>

Use L</foobar_v2> instead.

B<Author:> John Doe

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/zurborg/libmethod-signatures-withdocumentation-perl/issu es

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

David Zurborg <zurborg@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2015 by David Zurborg.

This is free software, licensed under:

The ISC License