/ 
Method-Signatures-WithDocumentation-1.000
River stage zero No dependents
/ Method::Signatures::WithDocumentation

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