P5EEx::Blue::podstyle - Style-guide for writing embedded POD documentation
In Perl, the term "Package" refers to a namespace in which subroutines and variables can be defined. In Perl, the developer usually uses Packages to write object-oriented code, so that a Package becomes a Module (i.e. a Class). Thus, in object-oriented perl, all three names (Package, Module, and Class) mean approximately the same thing.
Confusingly, in UML and Java, "packages" are groups of related classes. In Perl, related classes are usually kept in the same directory, so this concept is called a "Class Group" or "Group of Classes".
A Distribution is a set of all classes bundled up along with their support files (test scripts, examples, doc, etc.) and versioned together. A Distribution generally comes in a gzipped tar file (i.e. P5EEx-Blue-0.25.tar.gz).
The documentation specified here takes the form of a "head1" section, a "head2" section, or bullet list with specialized keywords.
# Every *.pm =head1 NAME # Every *.pm =head1 SYNOPSIS # Every *.pm =head1 DESCRIPTION # Main .pm in Distribution only =head1 Distribution: <Dist-name> <description> =item * Version: $Id: podstyle.pod,v 1.3 2001/11/30 16:00:52 spadkins Exp $ =head2 Distribution Requirements =head2 Distribution Design =head2 Class Groups: =item * Class Group: <Class-Group-name> <description> # Main .pm in Class Group only =head1 Class Group: <Class-Group-name> <description> =head2 Class Group Requirements =head2 Class Group Design =head2 Classes: =item * Class: <Class-name> <description> # Every *.pm (each if applicable) =head1 Class: <Class-name> <description> =item * Throws: <Exception-Name> =item * Deprecated: <Since-Version> <Planned-Discontinue-Version> =item * Since: <Version-Number> =head2 Class Requirements =head2 Class Design =head2 Capabilities: =item * Capability: <Capability-Name> <description> # Every *.pm (each if applicable) =head1 Attributes, Constants, Global Variables, Class Variables =head2 Public Attributes: [<Capability-Name>] =head2 Protected Attributes: [<Capability-Name>] =head2 Private Attributes: [<Capability-Name>] =item * Attribute: <Attribute-Name> <Type> <description> =item * Constant: <Attribute-Name> <Type> =item * Global Variable: <Attribute-Name> <Type> =item * Class Variable: <Attribute-Name> <Type> # Every *.pm (each if applicable) =head1 Constructor Methods: =head1 Public Methods: [<Capability-Name>] =head1 Protected Methods: [<Capability-Name>] =head1 Private Methods: [<Capability-Name>] # Every method (each if applicable) =head2 <Method-Name>() * Signature: <Sample-Usage-Illustrating-The-Signature> * Param: <Param-Name> <Type> <In/Out> <Undef-OK> * Return: <Return-Name> <Type> <Undef-OK> * Throws: <Exception-Name> * Deprecated: <Since-Version> <Planned-Discontinue-Version> * Since: <Version-Number> Sample Usage: # Every *.pm =head1 ACKNOWLEDGEMENTS =item * Author: <author> [< <email-address> >] =item * License: <license> =head1 SEE ALSO
In some pod file, there should exist the documentation for the entire distribution. There may be a naturally top-level package to put this in (i.e. P5EEx::Blue.pm), or you may need to create a separate pod file for this (i.e. P5EEx::Blue::distribution.pod).
The distribution documentation is composed of those specifications that apply to the entire set of classes and accompanying files.
The following documentation must be included in a the Distribution doc.
Perl version required to run the Distribution
Hard Dependencies (other Distributions, and their versions, required to be installed)
Soft Dependencies (other Distributions, and their versions, optionally used if installed)
All Exceptions Thrown by any Classes in the Distribution
List of Class Groups in the Distribution (every Class should belong to exactly one Class Group for the purposes of documentation)
A link to the Exceptions documentation
Requirements
Design
Note: Every P5EE-compliant distribution should include a single Exceptions.pm file (i.e. P5EEx::Blue::Exceptions.pm).
For each subset of classes in the distribution (typically a directory), there should be additional documentation for that Group of Classes.
Description
Platform Dependencies (OS/Hardware/Configuration)
References to any external specifications
Each Class file (*.pm) should have Class documentation.
Class Description
State/Transition Information (high level)
Allowed Implementation Variances
Security Constraints
References to any External Secifications
The documentation for the attributes of the Class should follow immediately after the Class documentation. For each attribute, consider including the following type of information.
Put the public attributes first (users of the class should access this attribute directly, rare!), then protected attributes (only other classes in this Class Group should access the attribute directly), then private attributes (only this class and derived classes should access the attribute directly).
Range of valid values
Intended Visibility (Public, Protected, Private)
Undef Value Behavior
Each method should have a section which explains the following. Multiple sections of doc should exist for each possible method signature.
Description and Behavior
State Transitions
Range of Valid Argument Values
Undef Argument Behavior
Range of Return Values
Algorithms Defined
Type and Cause of Exceptions
To install App::Context, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::Context
CPAN shell
perl -MCPAN -e shell install App::Context
For more information on module installation, please visit the detailed CPAN module installation guide.