The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Method::Signatures::WithDocumentation - use Method::Signatures with Sub::Documentation together

VERSION

version 1.000

SYNOPSIS

    use Method::Signatures::WithDocumentation;
    
    method foo (Str $text) :Purpose(Does something with text) {
        ...
    }

DESCRIPTION

This module extends Method::Signatures to grab out parameter definitions. It behaves also similiar to Sub::Documentation::Attributes, but with an important fix to let it work together with Pod::Weaver::Section::AutoDoc.

SUBROUTINE ATTRIBUTES

Each of the attributes (except Deprecated) requires a non-interpolated string. Please note that all parantheses must be balanced.

Name

Use another name instead of method/function for documentation.

Purpose

A brief description what the function/method does.

Pod

Free-text deeper description of whats going on.

Param

A description of a function/method param, suggested by the following format:

    method xxx ($foo, $bar) :Param($foo: This is foo) :Param($bar: This is bar) { ... }

Just the variable name (without modifiers like \, :, ? or !) followed by a colon and the description.

Author

Name of the author of the method/function, if it differs from the module author and the name should be explicity printed in the documentation.

Maybe used more than once, one for each author.

Returns

A free text what will be returned.

Throws

A free text what will be thrown in case of whatever.

Maybe used more than once, one for each case.

Example

A verbatim text, like a synopsis at the beginning of each module documentation.

Since

An identifier since when the method/function is available. For example a date or a version number.

Deprecated

This attributes marks the method/function as deprecated. The reason is optional.

SEE ALSO

FORMATTING TIPS

For some readers it might be confusing the read a subroutine definition with many attributes. There 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
        )
    { ... }

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