Method::Signatures::WithDocumentation - use Method::Signatures with Sub::Documentation together
version 1.000
use Method::Signatures::WithDocumentation; method foo (Str $text) :Purpose(Does something with text) { ... }
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.
Each of the attributes (except Deprecated) requires a non-interpolated string. Please note that all parantheses must be balanced.
Deprecated
Use another name instead of method/function for documentation.
A brief description what the function/method does.
Free-text deeper description of whats going on.
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.
\
:
?
!
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.
A free text what will be returned.
A free text what will be thrown in case of whatever.
Maybe used more than once, one for each case.
A verbatim text, like a synopsis at the beginning of each module documentation.
An identifier since when the method/function is available. For example a date or a version number.
This attributes marks the method/function as deprecated. The reason is optional.
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 ) { ... }
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.
David Zurborg <zurborg@cpan.org>
This software is Copyright (c) 2015 by David Zurborg.
This is free software, licensed under:
The ISC License
To install Method::Signatures::WithDocumentation, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Method::Signatures::WithDocumentation
CPAN shell
perl -MCPAN -e shell install Method::Signatures::WithDocumentation
For more information on module installation, please visit the detailed CPAN module installation guide.