Permalink
Browse files

Document a bunch of things.

  • Loading branch information...
1 parent dd5b89e commit fb264ff45d5f4b0e8477062bbf55f8fa41359fbe @rcaputo committed Jul 22, 2012
@@ -10,6 +10,34 @@ use Carp qw(confess);
=cut
+=head1 SYNOPSIS
+
+=xref module Pod::Plexus::Code::Attribute
+
+=xref module Pod::Plexus::Code::Method
+
+=cut
+
+
+=head1 DESCRIPTION
+
+[% m.name %] is a base class for objects that represent code within a
+distribution. Code objects are used to validate documentation:
+
+=over 4
+
+=item * Is everything documented?
+
+=item * Does all documentation refer to something in the code?
+
+=back
+
+Code objects are also used to include code examples in the
+documentation.
+
+=cut
+
+
=method new
=include Pod::Plexus boilerplate new
@@ -10,6 +10,32 @@ extends 'Pod::Plexus::Code';
=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.pacakge %] determines how the "method" variant of "=example"
+commands are interpreted and their resulting documentation is
+rendered.
+
+=cut
+
+
=attribute meta_entity
=include Pod::Plexus::Code attribute meta_entity
@@ -15,6 +15,24 @@ use Template::Stash;
=cut
+=head1 SYNOPSIS
+
+=example Pod::Plexus::Cli attribute _distribution
+
+=cut
+
+
+=head1 DESCRIPTION
+
+[% m.name %] represents an entire code distribution. It contains zero
+or more modules, each of which must contain documentation and code.
+
+[% m.name %] provides attributes and methods to access and manipulate
+modules and their documentation.
+
+=cut
+
+
$Template::Stash::SCALAR_OPS->{call} = sub {
my ($class, $method, @parameters) = @_;
return $class->$method(@parameters);
@@ -13,6 +13,20 @@ use Pod::Plexus::Util::PodElemental qw(blank_line cut_paragraph);
=cut
+=head1 SYNOPSIS
+
+TODO
+
+=cut
+
+
+=head1 DESCRIPTION
+
+TODO
+
+=cut
+
+
has name => (
is => 'ro',
isa => 'Str',
@@ -1,10 +1,28 @@
package Pod::Plexus::Matter::Pod;
# TODO - Edit pass 1 done.
+
=abstract A base class for Pod::Plexus wrappers around POD.
=cut
+
+=head1 SYNOPSIS
+
+=xref module Pod::Plexus::Matter::head1
+
+=cut
+
+
+=head1 DESCRIPTION
+
+[% m.package %] is a base class for Pod::Plexus objects that parse and
+manage Perl's plain old documentation (POD). The subclasses do most
+of the work, if not all of it.
+
+=cut
+
+
use Moose;
extends 'Pod::Plexus::Matter';
@@ -82,6 +82,7 @@ sub get_referent_matter {
my $element = $self->element();
chomp(my $content = $element->content());
die [
+ "((( $cache_name )))",
"Can't find matter referred to" .
" in '=" . $element->command() . " $content'" .
" at " . $self->module_pathname() .
@@ -7,11 +7,6 @@ package Pod::Plexus::Matter::abstract;
=cut
-=inherits Pod::Plexus::Matter head1 SYNOPSIS
-
-=cut
-
-
=head1 SYNOPSIS
package Reflex;
@@ -22,6 +17,7 @@ package Pod::Plexus::Matter::abstract;
=cut
+
=head1 DESCRIPTION
[% m.package %] defines how Pod::Plexus will parse "=abstract"
@@ -42,6 +38,7 @@ Abstracts typically render similar to this:
=cut
+
use Moose;
extends 'Pod::Plexus::Matter';
with 'Pod::Plexus::Matter::Role::DiscardBody';
@@ -6,6 +6,31 @@ package Pod::Plexus::Matter::after;
=cut
+
+=head1 SYNOPSIS
+
+ =after Package [attribute|method] symbol_name
+
+ The documentation for the symbol_name attribute or method will be
+ inherited. New content in the "=after" section will be added after
+ the inherited documentation.
+
+ =cut
+
+=cut
+
+
+=head1 DESCRIPTION
+
+[% m.package %] implenents the "=after" Pod::Plexus directive. This
+allows POD to incorporate POD from another package's attribute or
+method documentation and append new content.
+
+=include Pod::Plexus::Matter::inherits boilerplate expansions
+
+=cut
+
+
use Moose;
extends 'Pod::Plexus::Matter::inherits';
with 'Pod::Plexus::Matter::Role::AppendToBody';
@@ -2,10 +2,34 @@ package Pod::Plexus::Matter::attribute;
# TODO - Edit pass 0 done.
+
=abstract Document a class attribute in an inheritable way.
=cut
+
+=head1 SYNOPSIS
+
+ =attribute matter
+
+ "[Z<>% s.name %]" contains a hash table of Pod::Plexus::Matter
+ objects that have been added to the module using add_matter().
+
+ =cut
+
+=cut
+
+
+=head1 DESCRIPTION
+
+"=attribute" is a Pod::Weaver directive that documents an object
+attribute. Pod::Plexus::Matter::attribute remembers and represents
+attribute documentation. Pod::Plexus manages attribute documentation
+using these objects.
+
+=cut
+
+
use Moose;
extends 'Pod::Plexus::Matter::Code';
@@ -6,6 +6,31 @@ package Pod::Plexus::Matter::before;
=cut
+
+=head1 SYNOPSIS
+
+ =before Package [attribute|method] symbol_name
+
+ The documentation for the symbol_name attribute or method will be
+ inherited. New content in the "=before" section will be added
+ before the inherited documentation.
+
+ =cut
+
+=cut
+
+
+=head1 DESCRIPTION
+
+[% m.package %] implenents the "=before" Pod::Plexus directive. This
+allows POD to incorporate POD from another package's attribute or
+method documentation and append new content.
+
+=include Pod::Plexus::Matter::inherits boilerplate expansions
+
+=cut
+
+
use Moose;
extends 'Pod::Plexus::Matter::inherits';
with 'Pod::Plexus::Matter::Role::PrependToBody';
@@ -19,6 +19,7 @@ package Pod::Plexus::Matter::boilerplate;
=cut
+
=head1 DESCRIPTION
[% m.package %] defines how Pod::Plexus will parse "=boilerplate"
@@ -2,10 +2,33 @@ package Pod::Plexus::Matter::example::attribute;
# TODO - Edit pass 0 done.
+
=abstract Render an attribute implementation as a code example.
=cut
+
+=head1 SYNOPSIS
+
+Include an example from an attribute in the current package:
+
+ =example attribute attribute_name
+
+Include an attribute from another package as an example here:
+
+ =example AnotherPackage attribute attribute_name
+
+=cut
+
+
+=head1 DESCRIPTION
+
+[% m.package %] objects manage, represent, and render code examples
+from actual code.
+
+=cut
+
+
use Moose;
extends 'Pod::Plexus::Matter::example';
@@ -2,10 +2,30 @@ package Pod::Plexus::Matter::example::module;
# TODO - Edit pass 0 done.
+
=abstract Render the code for a whole module as an example.
=cut
+
+=head1 SYNOPSIS
+
+Use an entire module as an example:
+
+ =example SomePackageName
+
+=cut
+
+
+=head1 DESCRIPTION
+
+[% m.package %] objects mange and render examples using modules'
+entire implementations. It's most useful for small modules or
+programs.
+
+=cut
+
+
use Moose;
extends 'Pod::Plexus::Matter::example';
@@ -2,6 +2,7 @@ package Pod::Plexus::Matter::head1;
# TODO - Edit pass 0 done.
+
=abstract Add Pod::Plexus semantics to plain POD head1 sections.
=cut
@@ -6,6 +6,39 @@ package Pod::Plexus::Matter::inherits;
=cut
+
+=head1 SYNOPSIS
+
+ =inherits Package [attribute|method] symbol_name
+
+ =cut
+
+=cut
+
+
+=boilerplate expansions
+
+Template symbols will be evaluated in the inheritor's namespace, so
+things like "[Z<>% m.package %]" will render correctly.
+
+These directives are POD sections for the sake of POD correctness and
+editor highlighting and folding. They may not contain content,
+however, since the content will be inherited from elsewhere.
+
+=cut
+
+
+=head1 DESCRIPTION
+
+[% m.package %] implements the "=inherits" Pod::Plexus directive. It
+allows POD in one module to incorporate attribute or method
+documentation from another module.
+
+=include boilerplate expansions
+
+=cut
+
+
use Moose;
extends 'Pod::Plexus::Matter::include';
Oops, something went wrong. Retry.

0 comments on commit fb264ff

Please sign in to comment.