Add more documentation.

Regrettably, Pod::Plexus doesn't seem to be making the documentation
process much more joyful.  It is giving me some peace of mind that my
docs are less likely to become obsolete as things change, and that's
worth the price of admission so far.

pod-plexus/lib/Pod/Plexus.pm

@@ -70,11 +70,12 @@ L<Pod::Weaver::Plugin::PodPlexus> is an ongoing attempt to integrate
 Pod::Plexus with Pod::Weaver, if it's possible.  Help wanted!
 
 The L<podplexus> command line utility is used to speed up development
-and testing.  I'm looking for help making it a stand-alone utility for
+and testing.  Help wanted to make it a useful stand-alone tool for
 people who would rather not use Dist::Zilla.
 
 Pod::Plexus leans heavily on L<PPI> and L<Moose> for code analysis.
-It uses L<Pod::Elemental> to wrangle documentation.
+It uses L<Pod::Elemental> to wrangle documentation.  Patches to reduce
+the number and/or complexity of dependencies are very welcome.
 
 In its default state, Pod::Plexus requires L<Pod::Weaver> or something
 like it to gather and render =method and =attribute sections.  POD can

pod-plexus/lib/Pod/Plexus/Cli.pm

@@ -13,40 +13,21 @@ use File::Find;
 
 =method new_with_options
 
-[% s.name %] constructs one new [% m.package %] object, using
-values from the command line to populate constructor parameters.
-See L</PUBLIC ATTRIBUTES> for constructor options and the command line
-switches that populate them.
-
-=cut
-
-
-=skip method usage
-
-=skip attribute usage
-
-=skip attribute ARGV
-
-=skip method extra_argv
-
-=skip attribute extra_argv
-
-=skip method help_flag
-
-=skip attribute help_flag
-
-=skip method process_argv
+[% s.name %] is inherited from MooseX::Getopt.  It creates one new [%
+m.package %] object from command line parameters.  See L</PUBLIC
+ATTRIBUTES> for constructor options and the command line switches that
+populate them.
 
 =cut
 
 
 =attribute lib
 
-[% s.name %] contains a list of distribution directories from which
-modules will be collected, indexed and possibly rendered.  By default
-it contains a single directory: "./lib".
+The "[% s.name %]" attribute contains a list of distribution
+directories from which modules will be collected, indexed and possibly
+rendered.  By default it contains a single directory: "./lib".
 
-[% s.name %] is populated by one or more --[% s.name %] command line
+"[% s.name %]" is populated by one or more --[% s.name %] command line
 switches.
 
 =cut
@@ -62,10 +43,10 @@ has lib => (
 
 =attribute module
 
-[% s.name %] is an array of specific modules to render.  All eligible
-files will be rendered if none are specified.
+"[% s.name %]" contains an array of specific modules to render.  All
+eligible files will be rendered if none are specified.
 
-[% s.name %] is populated by one or more --[% s.name %] command line
+"[% s.name %]" is populated by one or more --[% s.name %] command line
 switches.
 
 =cut
@@ -82,6 +63,13 @@ has module => (
 );
 
 
+=attribute verbose
+
+The "[% s.name %]" attribute (and therefore the --[% s.name %] command
+line flag) turns on additional stderr information when true.
+
+=cut
+
 has verbose => (
 	is            => 'rw',
 	isa           => 'Bool',
@@ -90,17 +78,6 @@ has verbose => (
 );
 
 
-=attribute _distribution
-
-[% s.name %] contains a Pod::Plexus::Distribution object.  This
-object is populated and driven by [% m.package %].
-
-[% s.name %] is populated by the --[% s.name %] command line switch.
-
-=example attribute _distribution
-
-=cut
-
 has _distribution => (
 	is      => 'ro',
 	isa     => 'Pod::Plexus::Distribution',
@@ -118,7 +95,7 @@ has _distribution => (
 [% s.name %] tests whether a file at a RELATIVE_PATH is eligible to
 be documented.  Currently only ".pm" files are eligible.
 
-=example method is_indexable_file
+=example method collect_lib_files
 
 =cut
 
@@ -135,12 +112,10 @@ sub is_indexable_file {
 
 =method collect_lib_files
 
-[% s.name %] collects files that are eligible for documenting.  It
-uses File::Find to descend into directories in the "lib" directories.
-Each file that is_indexable_file() approves is added to the
-distribution for later processing.
-
-=example method collect_lib_files
+[% s.name %] collects files in the distribution that are eligible for
+documenting.  It uses File::Find to descend into directories in the
+"lib" attribute.  Each file that is_indexable_file() approves is added
+to the distribution for later processing.
 
 =cut
 
@@ -167,14 +142,18 @@ sub collect_lib_files {
 
 =method run
 
-[% s.name %] runs the Pod::Plexus command-line interface.  All
+[% s.name %] runs the Pod::Plexus command-line implementation.  All
 runtime parameters are taken from [% m.package %] public attributes.
 Thanks to MooseX::Getopt, those attributes are automatically populated
 from corresponding command line arguments.
 
-[% s.name %] collects all the modules in all the lib() directories.
+[% s.name %] collects all the modules in all the "lib" directories.
 Each module is added to the Pod::Plexus::Distribution so that it's
-known by the time cross references are resolved.
+known by the time cross references are resolved.  Each module is
+scanned by Pod::Plexus::Module, which finds and caches pertinent
+information in a Pod::Plexus::Module::Code or
+Pod::Plexus::Module::Docs object for manipulation and rendering into
+POD later.
 
 =example method run
 
@@ -218,7 +197,15 @@ sub run {
 
 		# TODO - Write to a file, if requested.
 
-		print $rendered_pod;
+		print(
+			"----------\n",
+			"----------\n",
+			"----------\n",
+			$rendered_pod,
+			"----------\n",
+			"----------\n",
+			"----------\n",
+		);
 	}
 
 	# TODO - Render to files, if appropriate.

pod-plexus/lib/Pod/Plexus/Matter.pm

@@ -1,6 +1,8 @@
 package Pod::Plexus::Matter;
 
-=abstract A generic expandable documentation reference.
+=abstract A generic segment of documentation matter.
+
+=cut
 
 =head1 SUBCLASSES
 
@@ -15,13 +17,21 @@ use Pod::Plexus::Util::PodElemental qw(cleanup_element_arrayref);
 use Storable qw(dclone);
 
 
+=method is_inheritable
+
+The [% s.name %] flag tells Pod::Plexus::Module::Docs whether a piece
+of documentation matter may be inherited through "=inherits",
+"=before" and "=after".  It is false by default.
+
+=cut
+
 sub is_inheritable { 0 }
 
 
 =attribute module
 
-[% s.name %] holds the Pod::Plexus::Module that contains this
-documentation section.
+"[% s.name %]" holds the Pod::Plexus::Module that contains this
+documentation matter.
 
 =cut
 
@@ -39,20 +49,42 @@ has module => (
 );
 
 
+=attribute name
+
+Most documentation matter has a name.  The "[% s.name %]" attribute
+contains that name for referencing and documentation expansion
+purposes.
+
+=cut
+
 has name => (
 	is      => 'rw',
 	isa     => 'Str',
 	default => "",
 );
 
 
+=inherits Pod::Plexus::Cli attribute verbose
+
+=cut
+
 has verbose => (
 	is       => 'ro',
 	isa      => 'Bool',
 	required => 1,
 );
 
 
+=attribute docs
+
+The current Pod::Plexus::Matter object exists within its module's
+documentation.  The "[% s.name %]" attribute holds the documentation
+for the entire module.  Subclasses use it and "[% s.name %]_index" to
+parse their documentation and replace themselves with
+Pod::Plexus::Matter objects.
+
+=cut
+
 has docs => (
 	is       => 'ro',
 	isa      => 'ArrayRef[Pod::Elemental::Paragraph|Pod::Plexus::Matter]',
@@ -61,13 +93,42 @@ has docs => (
 );
 
 
+=attribute docs_index
+
+"[% s.name %]" contains this Pod::Plexus::Matter object's index inside
+the "docs" attribute.  It's used to splice a new [% m.name %] object
+into the documentation where the corresponding Pod::Plexus command
+appeared.
+
+=cut
+
 has docs_index => (
 	is       => 'ro',
 	isa      => 'Int',
 	required => 1,
 );
 
 
+=boilerplate doc_attribute
+
+Each Pod::Plexus::Matter object represents up to three pieces of
+documentation: (1) An optional documentation prefix, which is often a
+"=head" or "=item" command of some sort.  (2) The documentation body,
+which is the section's main prose.  (3) An optional documentation
+suffix, which is often just "=cut".
+
+=cut
+
+
+=attribute doc_prefix
+
+=include boilerplate doc_attribute
+
+"[% s.name %]" contains the POD section prefix.  Subclasses often
+override it to format their data into POD.
+
+=cut
+
 has doc_prefix => (
 	is      => 'rw',
 	isa     => 'ArrayRef[Pod::Elemental::Paragraph]',
@@ -81,6 +142,20 @@ has doc_prefix => (
 );
 
 
+=attribute doc_body
+
+=include boilerplate doc_attributes
+
+"[% s.name %]" contains the main body of documentation for a piece of
+Pod::Plexus::Matter.
+
+Pod::Plexus::Matter includes a couple helper methods to deal with
+section bodies.  See extract_my_section() and discard_my_section() for
+standard ways to deal with text in a Pod::Plexus documentation
+section.
+
+=cut
+
 has doc_body => (
 	is      => 'rw',
 	isa     => 'ArrayRef[Pod::Elemental::Paragraph|Pod::Plexus::Matter]',
@@ -95,6 +170,17 @@ has doc_body => (
 );
 
 
+=attribute doc_suffix
+
+=include boilerplate doc_attributes
+
+"[% s.name %]" ends the documentation represented by a
+Pod::Plexus::Matter object.  It's mostly either "=cut" for matter that
+represents entire POD sections.  It's often empty for matter
+representing inclusions that aren't entire sections on their own.
+
+=cut
+
 has doc_suffix => (
 	is      => 'rw',
 	isa     => 'ArrayRef[Pod::Elemental::Paragraph|Pod::Plexus::Matter]',
@@ -108,18 +194,56 @@ has doc_suffix => (
 );
 
 
+=boilerplate cloning_docs
+
+Pod::Plexus is "documentation by reference".  Dereferencing is
+implemented by cloning bits of the objects representing documentation.
+
+=cut
+
+
+=method clone_prefix
+
+[% s.name %]() is a helper method to clone a Pod::Plexus::Matter
+object's "doc_prefix" attribute, so that inheritors don't need to
+worry about modifications from a distance.
+
+=include boilerplate cloning_docs
+
+=cut
+
 sub clone_prefix {
 	my $self = shift;
 	return dclone $self->doc_prefix();
 }
 
 
+=method clone_body
+
+[% s.name %]() is a helper method to clone a Pod::Plexus::Matter
+object's "doc_body" attribute, so that inheritors don't need to worry
+about modifications from a distance.
+
+=include boilerplate cloning_docs
+
+=cut
+
 sub clone_body {
 	my $self = shift;
 	return dclone $self->doc_body();
 }
 
 
+=method clone_suffix
+
+[% s.name %]() is a helper method to clone a Pod::Plexus::Matter
+object's "doc_suffix" attribute, so that inheritors don't need to
+worry about modifications from a distance.
+
+=include boilerplate cloning_docs
+
+=cut
+
 sub clone_suffix {
 	my $self = shift;
 	return dclone $self->doc_suffix();