NAME
Dist::Zilla::Plugin::Pod::Spiffy - make your documentation look spiffy as HTML
SYNOPSIS
In your POD:
=head2 C<my_super_function>
=
for
pod_spiffy in
no
args | out error
undef
or list|out hashref
This function takes two arguments, one of them is mandatory. On
error it returns either
undef
or an empty list, depending on the
context. On success, it returns a hashref.
...
=head1 REPOSITORY
=
for
pod_spiffy start github section
Fork this module on https://github.com/zoffixznet/Dist-Zilla-Plugin-Pod-Spiffy
=
for
pod_spiffy end github section
...
=head1 AUTHORS
=
for
pod_spiffy authors ZOFFIX JOE SHMOE
=head1 CONTRIBUTORS
=
for
pod_spiffy authors SOME CONTRIBUTOR
In your dist.ini
:
[Pod::Spiffy]
DESCRIPTION
This Dist::Zilla plugin lets you make your documentation look spiffy as HTML, by adding meaningful icons. If you're viewing this document as HTML, you can see available icons below.
The main idea behind this module isn't so much the looks, however, but the provision of visual hints and clues about various sections of your documentation, and more importantly the arguments and return values of the methods/functions.
HISTORY
I was impressed by ETHER's work on Acme::CPANAuthors::Nonhuman (the including author avatars in the docs part) and appreciated the added value HTML content can bring to the POD in my Acme::Dump::And::Dumper.
While working on the implementation of the horribly inconsistent WWW::Goodreads, I wanted my users to not have to remember the type of return values for 74+ methods. That's when I thought up the idea of including icons to give hints of the return types.
THEME
The current theme is hardcoded to use http://zoffix.com/CPAN/Dist-Zilla-Plugin-Pod-Spiffy/icons/
However, since most icons are size-unbound, themeing should be extremely easy in the future, and configuration option will be provided very soon.
NOTE ON SCALARS
I realize that hashrefs, subrefs, arrayrefs, and the ilk are all scalars, but this documentation and the icons by scalars mean the plain, non-reference types; i.e. strings and numbers (42
, "foo"
, etc.)
IN YOUR POD
To spiffy-up your POD, use the =for
POD command, followed by pod_spiffy
, followed by codes (see SYNOPSIS for examples). For icons, you can specify multiple icon codes separated with a pipe character (|
). For example:
=
for
pod_spiffy in
no
args
=
for
pod_spiffy in
no
args | out error
undef
list
You can have any amount of whitespace between individual words of the codes (but you must have at least some whitespace). Whitespace around the |
separator is irrelevant.
The following codes are currently available:
INPUT ARGUMENTS ICONS
These icons provide hints on what your sub/method takes as an argument.
in no args
Icon:
=
for
pod_spiffy in
no
args
![](http://zoffix.com/CPAN/Dist-Zilla-Plugin-Pod-Spiffy/icons/in-no-args.png)
Use this icon to indicate your sub/method does not take any arguments.
in scalar
Icon:
=
for
pod_spiffy in
scalar
![](http://zoffix.com/CPAN/Dist-Zilla-Plugin-Pod-Spiffy/icons/in-scalar.png)
Use this icon to indicate your sub/method takes a plain scalar as an argument.
in scalar scalar optional
Icon:
=
for
pod_spiffy in
scalar
scalar
optional
![](http://zoffix.com/CPAN/Dist-Zilla-Plugin-Pod-Spiffy/icons/in-scalar-scalar-optional.png)
Use this icon to indicate your sub/method takes as arguments one mandatory and one optional arguments, both of which are plain scalars.
in arrayref
Icon:
=
for
pod_spiffy in arrayref
![](http://zoffix.com/CPAN/Dist-Zilla-Plugin-Pod-Spiffy/icons/in-arrayref.png)
Use this icon to indicate your sub/method takes an arrayref as an argument.
in hashref
Icon:
=
for
pod_spiffy in hashref
![](http://zoffix.com/CPAN/Dist-Zilla-Plugin-Pod-Spiffy/icons/in-hashref.png)
Use this icon to indicate your sub/method takes an hashref as an argument.
in key value
Icon:
=
for
pod_spiffy in key value
![](http://zoffix.com/CPAN/Dist-Zilla-Plugin-Pod-Spiffy/icons/in-key-value.png)
Use this icon to indicate your sub/method takes a list of key/value pairs as an argument (e.g. ->method( foo => 'bar', ber => 'biz' );
.
in list
Icon:
=
for
pod_spiffy in list
![](http://zoffix.com/CPAN/Dist-Zilla-Plugin-Pod-Spiffy/icons/in-list.png)
Use this icon to indicate your sub/method takes a list of scalars as an argument (e.g. qw/foo bar baz ber/
)
in object
Icon:
=
for
pod_spiffy in object
![](http://zoffix.com/CPAN/Dist-Zilla-Plugin-Pod-Spiffy/icons/in-object.png)
Use this icon to indicate your sub/method takes an object as an argument.
in scalar optional
Icon:
=
for
pod_spiffy in
scalar
optional
![](http://zoffix.com/CPAN/Dist-Zilla-Plugin-Pod-Spiffy/icons/in-scalar-optional.png)
Use this icon to indicate your sub/method takes a single optional argument that is a scalar.
in scalar or arrayref
Icon:
=
for
pod_spiffy in
scalar
or arrayref
![](http://zoffix.com/CPAN/Dist-Zilla-Plugin-Pod-Spiffy/icons/in-scalar-or-arrayref.png)
Use this icon to indicate your sub/method takes either a plain scalar or an arrayref as an argument.
in subref
Icon:
=
for
pod_spiffy in subref
![](http://zoffix.com/CPAN/Dist-Zilla-Plugin-Pod-Spiffy/icons/in-subref.png)
Use this icon to indicate your sub/method takes a subref as an argument.
OUTPUT ON ERROR ICONS
These icons are to indicate what your sub/method returns if an error occurs during its execution.
out error exception
Icon:
=
for
pod_spiffy out error exception
![](http://zoffix.com/CPAN/Dist-Zilla-Plugin-Pod-Spiffy/icons/out-error-exception.png)
Use this icon to indicate your sub/method on error throws an exception.
out error undef or list
Icon:
=
for
pod_spiffy out error
undef
or list
Use this icon to indicate your sub/method on error returns either undef
or an empty list, depending on the context.
out error undef
Icon:
=
for
pod_spiffy out error
undef
![](http://zoffix.com/CPAN/Dist-Zilla-Plugin-Pod-Spiffy/icons/out-error-undef.png)
Use this icon to indicate your sub/method on error returns undef
(regardless of the context).
OUTPUT ICONS
These icons are to indicate what your sub/method returns after a successful execution.
out scalar
Icon:
=
for
pod_spiffy out
scalar
![](http://zoffix.com/CPAN/Dist-Zilla-Plugin-Pod-Spiffy/icons/out-scalar.png)
Use this icon to indicate your sub/method returns a plain scalar.
out arrayref
Icon:
=
for
pod_spiffy out arrayref
![](http://zoffix.com/CPAN/Dist-Zilla-Plugin-Pod-Spiffy/icons/out-arrayref.png)
Use this icon to indicate your sub/method returns an arrayref.
out hashref
Icon:
=
for
pod_spiffy out hashref
![](http://zoffix.com/CPAN/Dist-Zilla-Plugin-Pod-Spiffy/icons/out-hashref.png)
Use this icon to indicate your sub/method returns a hashref.
out key value
Icon:
=
for
pod_spiffy out key value
![](http://zoffix.com/CPAN/Dist-Zilla-Plugin-Pod-Spiffy/icons/out-key-value.png)
Use this icon to indicate your sub/method returns a list of key value pairs (i.e., return is suitable to assign to a hash).
out list
Icon:
=
for
pod_spiffy out list
![](http://zoffix.com/CPAN/Dist-Zilla-Plugin-Pod-Spiffy/icons/out-list.png)
Use this icon to indicate your sub/method returns a list of things (i.e., return is suitable to assign to an array).
out list or arrayref
Icon:
=
for
pod_spiffy out list or arrayref
![](http://zoffix.com/CPAN/Dist-Zilla-Plugin-Pod-Spiffy/icons/out-list-or-arrayref.png)
Use this icon to indicate your sub/method returns either a list of things or an arrayref, depending on the context.
out subref
Icon:
=
for
pod_spiffy out subref
![](http://zoffix.com/CPAN/Dist-Zilla-Plugin-Pod-Spiffy/icons/out-subref.png)
Use this icon to indicate your sub/method returns a subref.
out object
Icon:
=
for
pod_spiffy out object
![](http://zoffix.com/CPAN/Dist-Zilla-Plugin-Pod-Spiffy/icons/out-object.png)
Use this icon to indicate your sub/method returns a object.
SECTION ICONS
To use a section icon, you need to indicate both the start of the section and the end of it, e.g.:
=
for
pod_spiffy start github section
=head3 GITHUB REPO
Fork this module on github https://github.com/zoffixznet/Dist-Zilla-Plugin-Pod-Spiffy
=
for
pod_spiffy end github section
Available icons are:
Github Repo
=
for
pod_spiffy start github section
Fork this module on GitHub:
=
for
pod_spiffy end github section
This is an example
Authors
=
for
pod_spiffy start author section
Joe Shmoe wrote this module
=
for
pod_spiffy end author section
This is an example
See also: "CPAN Authors" section below, for a way to include author avatars.
Contributors
=
for
pod_spiffy start contributors section
Joe More also contributed to this module
=
for
pod_spiffy end contributors section
This is an example
See also: "CPAN Authors" section below, for a way to include author avatars.
Bugs
=
for
pod_spiffy start bugs section
Report bugs
for
this module on
=
for
pod_spiffy end bugs section
This is an example
Code
=
for
pod_spiffy start code section
"Yey\n"
for
1..42;
=
for
pod_spiffy end code section
This is an example
I'm unsure of the use for this icon. Originally it was planned to be used with the SYNOPSIS code. The icon will likely be changed in appearance and the code
section might become more versatile, to be used with all chunks of code.
Warning
=
for
pod_spiffy start warning section
Warning! If you
try
this something might explode!
=
for
pod_spiffy end warning section
This is an example
Use this section icon to indicate a warning.
Experimental
=
for
pod_spiffy start experimental section
This method is still experimental!
=
for
pod_spiffy end experimental section
This is an example
Use this section to hint about the features described being experimental.
OTHER FEATURES
CPAN Authors
=
for
pod_spiffy author ZOFFIX ETHER MSTROUT
Adds an avatar of the author, and their PAUSE ID. To use this feature use authors
code, followed by a whitespace separated list of PAUSE author IDs, for example:
Example:
Horizontal Rule
=
for
pod_spiffy hr
Example:
A simple horizontal rule. You can use it, for example, to separate groups of methods.
REPOSITORY
Fork this module on GitHub: https://github.com/zoffixznet/Dist-Zilla-Plugin-Pod-Spiffy
BUGS
To report bugs or request features, please use https://github.com/zoffixznet/Dist-Zilla-Plugin-Pod-Spiffy/issues
If you can't access GitHub, you can email your request to bug-Dist-Zilla-Plugin-Pod-Spiffy at rt.cpan.org
AUTHOR
LICENSE
You can use and distribute this module under the same terms as Perl itself. See the LICENSE
file included in this distribution for complete details.