Permalink
Browse files

Satsify some SYNOPSIS and DESCRIPTION requirements.

  • Loading branch information...
1 parent cef0cf5 commit dd5b89eb958b5ece666049572bf8f29685bcf302 @rcaputo committed Dec 28, 2011
@@ -16,7 +16,6 @@ use Carp qw(confess);
=cut
-
=attribute name
[% SWITCH m.package %]
@@ -15,6 +15,32 @@ class_type('Moose::Meta::Role::Attribute');
=cut
+=head1 SYNOPSIS
+
+ =head1 SOME EXAMPLES
+
+ An example coming from the current package:
+
+ =example attribute in_this_package
+
+ An example coming from some other package:
+
+ =example Some::Other::Package attribute in_another_package
+
+ =cut
+
+=cut
+
+
+=head1 DESCRIPTION
+
+[% m.package %] determines how the "attribute" variant of "=example"
+commands are interpreted and their resulting documentation is
+rendered.
+
+=cut
+
+
has '+meta_entity' => (
isa => 'Class::MOP::Attribute | Moose::Meta::Role::Attribute',
);
@@ -12,7 +12,7 @@ extends 'Pod::Plexus::Matter';
sub is_top_level { 1 }
-=after as_pod_elementals
+=after method as_pod_elementals
Pod::Plexus directives don't render as POD, so [% s.name %]() always
returns an empty list.
@@ -12,10 +12,14 @@ package Pod::Plexus::Matter::abstract;
=cut
+=head1 SYNOPSIS
+ package Reflex;
+ =abstract Class library for flexible, reactive programming.
+
+ =cut
-=head1 SYNOPSIS
=cut
=head1 DESCRIPTION
@@ -24,15 +28,7 @@ package Pod::Plexus::Matter::abstract;
meta-POD and generate the resulting POD documentation. Abstracts are
rewritten in the POD standard style. See the L</SYNOPSIS>.
-Pod::Plexus:
-
- package Reflex;
-
- =abstract Class library for flexible, reactive programming.
-
- =cut
-
-Renders as:
+Abstracts typically render similar to this:
=head1 NAME
@@ -6,6 +6,19 @@ package Pod::Plexus::Matter::boilerplate;
=cut
+
+=head1 SYNOPSIS
+
+ =boilerplate section_body_handler
+
+ [Z<>% SET command = c.match('::([a-z]+)').0 %]
+ The POD associated with the "=[Z<>% command %]" command will be
+ extracted and used as the body of any generated POD section.
+
+ =cut
+
+=cut
+
=head1 DESCRIPTION
[% m.package %] defines how Pod::Plexus will parse "=boilerplate"
@@ -23,6 +23,60 @@ use Carp qw(confess);
=cut
+=head1 SYNOPSIS
+
+Include the implementation of an attribute, method or function within
+documentation.
+
+ =head1 SOME EXAMPLES
+
+ An example attribute:
+
+ =example Module attribute foo
+
+ An example method:
+
+ =example Module method foo
+
+ An example function:
+
+ =example Module function foo
+
+ =cut
+
+Entire modules can also be used as examples. It's best if they're
+really short.
+
+ =head1 A MODULE EXAMPLE
+
+ A module example:
+
+ =example module Module
+
+ =cut
+
+=cut
+
+
+=head1 DESCRIPTION
+
+"=example" describes some source code within the distribution.
+Pod::Plexus will locate that code, format it as an example, and
+replace the "=example" command with it.
+
+
+[% m.package %] delegates the actual semantics and POD rendering to
+subclasses:
+
+=over 4
+
+=toc ^Pod::Plexus::Matter::example::
+
+=back
+
+=cut
+
+
=attribute referent_name
"[% s.name %]" contains the name of the subroutine, method, attribute
@@ -6,6 +6,33 @@ package Pod::Plexus::Matter::example::function;
=cut
+
+=head1 SYNOPSIS
+
+ =head1 SOME EXAMPLES
+
+ An example coming from the current package:
+
+ =example function in_this_package
+
+ An example coming from some other package:
+
+ =example Some::Other::Package function in_another_package
+
+ =cut
+
+=cut
+
+
+=head1 DESCRIPTION
+
+[% m.package %] determines how the "function" variant of "=example"
+commands are interpreted and their resulting documentation is
+rendered.
+
+=cut
+
+
use Moose;
extends 'Pod::Plexus::Matter::example';
@@ -6,6 +6,33 @@ package Pod::Plexus::Matter::example::method;
=cut
+
+=head1 SYNOPSIS
+
+ =head1 SOME EXAMPLES
+
+ An example coming from the current package:
+
+ =example method in_this_package
+
+ An example coming from some other package:
+
+ =example Some::Other::Package method in_another_package
+
+ =cut
+
+=cut
+
+
+=head1 DESCRIPTION
+
+[% m.package %] determines how the "method" variant of "=example"
+commands are interpreted and their resulting documentation is
+rendered.
+
+=cut
+
+
use Moose;
extends 'Pod::Plexus::Matter::example';
@@ -6,6 +6,29 @@ package Pod::Plexus::Matter::function;
=cut
+
+=head1 SYNOPSIS
+
+ =function blank_line
+
+ Prose describing the blank_line() function.
+
+ =cut
+
+=cut
+
+
+=head1 DESCRIPTION
+
+"=function" describes a function in the current package. It behaves
+almost exactly like "=method", but its symbols exist within a
+different namespace. Pod::Weaver to gather functions into a different
+section than methods, and Pod::Plexus can tell the difference between
+functions and methods.
+
+=cut
+
+
use Moose;
extends 'Pod::Plexus::Matter::Code';
@@ -6,6 +6,33 @@ package Pod::Plexus::Matter::head1;
=cut
+
+=head1 SYNOPSIS
+
+ =head1 SYNOPSIS
+
+ =head1 SYNOPSIS
+
+ ...
+
+ =cut
+
+ =cut
+
+=cut
+
+
+=head1 DESCRIPTION
+
+POD "=head1" sections tend to be important. [% m.package %] parses
+them so Pod::Plexus can analyze and validate them. For example,
+Pod::Plexus expects every module to include a "=head1 SYNOPSIS" and
+"=head1 DESCRIPTION". It couldn't verify their presence without this
+module.
+
+=cut
+
+
use Moose;
extends 'Pod::Plexus::Matter::Pod';
with 'Pod::Plexus::Matter::Role::AbsorbedBody';
@@ -6,6 +6,50 @@ package Pod::Plexus::Matter::method;
=cut
+
+=head1 SYNOPSIS
+
+ =method new_from_element
+
+ Prose documenting the method.
+
+ =cut
+
+=cut
+
+
+=head1 DESCRIPTION
+
+"=method" is a Pod::Weaver directive. Pod::Plexus::Matter::method
+remembers method documentation and allows Pod::Plexus to manipulate
+them as well.
+
+Method documentation can be imported into other places using
+"=inherits", "=before", "=after" and "=include".
+
+=over 4
+
+=xref method Pod::Plexus::Matter::after
+
+=xref method Pod::Plexus::Matter::before
+
+=xref method Pod::Plexus::Matter::include
+
+=xref method Pod::Plexus::Matter::inherits
+
+=back
+
+Method documentation can be referenced using "=xref".
+
+=over 4
+
+=xref method Pod::Plexus::Matter::xref
+
+=back
+
+=cut
+
+
use Moose;
extends 'Pod::Plexus::Matter::Code';
@@ -16,6 +16,42 @@ use Carp qw(croak);
=cut
+=head1 SYNOPSIS
+
+ =skip method BUILD
+
+ =skip attribute verbose
+
+ =cut
+
+=cut
+
+
+=boilerplate skip_purpose
+
+Often a class may implement or inherit private methods that look
+public because their names don't begin with underscores. "=skip"
+directives can eliminate these inadvertently public from the resulting
+documentation.
+
+=cut
+
+
+=head1 DESCRIPTION
+
+[% m.package %] implements the "=skip" directive, which tells
+Pod::Plexus which symbols to skip when compiling and validating a
+module's documentation.
+
+=include boilerplate skip_purpose
+
+=head2 Variants
+
+=toc Pod::Plexus::Matter::skip::
+
+=cut
+
+
=boilerplate new_from_element
[% s.name %]() creates a new [% m.package %]::attribute or
@@ -24,6 +60,7 @@ syntax.
=cut
+
sub new_from_element {
my ($class, %args) = @_;
Oops, something went wrong.

0 comments on commit dd5b89e

Please sign in to comment.