Updated documentation for Parrot::*

git-svn-id: https://svn.parrot.org/parrot/trunk@5757 d31e2699-5ff4-0310-a27c-f18f2fbe73fe

lib/Parrot/BuildUtil.pm

@@ -7,6 +7,8 @@ lib/Parrot/BuildUtil.pm - Build Utility
 
 =head1 DESCRIPTION
 
+=head2 Functions
+
 =over 4
 
 =cut

lib/Parrot/Configure/RunSteps.pm

@@ -12,6 +12,8 @@ F<Configure.pl>. It should be edited when adding a new step. For more
 information on Parrot's configuration system, and how to add new steps,
 see F<docs/configuration.pod>.
 
+=head2 Functions
+
 =over 4
 
 =cut
@@ -99,7 +101,7 @@ sub runsteps {
 
 =over 4
 
-=item L<Parrot::Configure::Step>
+=item C<Parrot::Configure::Step>
 
 =item F<docs/configuration.pod>
 

lib/Parrot/Distribution.pm

@@ -12,15 +12,15 @@ Parrot::Distribution - Parrot Distribution Directory
 
 =head1 DESCRIPTION
 
-The Parrot distribution directory knows all kinds of stuff about the
-contents of the distribution.
+C<Parrot::Distribution> knows all kinds of stuff about the contents of
+the distribution.
 
 This is a subclass of C<Parrot::Docs::Directory> so that it can be used
 to build the HTML docs. There may come a time when it is necessary to 
 make C<file_class()> and C<directory_class()> dynamic so that different
 file methods can be used depending on the circumstances.
 
-=head2 Methods
+=head2 Class Methods
 
 =over 4
 
@@ -68,6 +68,12 @@ sub new
 	die "Failed to find Parrot distribution root\n";
 }
 
+=back
+
+=head2 Instance Methods
+
+=over 4
+
 =item C<c_source_file_directories()>
 
 Returns the directories which contain C source files.

lib/Parrot/Docs/Directory.pm

@@ -3,20 +3,19 @@
 
 =head1 NAME
 
-Parrot::Docs::Directory - Docs-related Directory
+Parrot::Docs::Directory - Docs-Related Directory
 
 =head1 SYNOPSIS
 
 	use Parrot::Docs::Directory;
-	my $dir = Parrot::Docs::Directory->new('parrot');
 
 =head1 DESCRIPTION
 
-This C<Parrot::IO::Directory> subclass creates C<Parrot::Docs::Files>.
+This C<Parrot::Docs::Directory> subclass creates C<Parrot::Docs::Files>.
 
 It's used by the documentation tools in F<tools/docs>.
 
-=head2 Methods
+=head2 Class Methods
 
 =over
 
@@ -53,6 +52,12 @@ sub directory_class
 	return 'Parrot::Docs::Directory';
 }
 
+=back
+
+=head2 Instance Methods
+
+=over 4
+
 =item C<files_of_type($type, $recursive, $ignore)>
 
 Use this to get a list of the files of a particular type.
@@ -95,7 +100,11 @@ sub files_of_type
 
 =head1 SEE ALSO
 
-C<Parrot::Docs::File>.
+=over 4
+
+=item C<Parrot::Docs::File>
+
+=back
 
 =cut
 

lib/Parrot/Docs/File.pm

@@ -3,7 +3,7 @@
 
 =head1 NAME
 
-Parrot::Docs::File - Docs-related file methods
+Parrot::Docs::File - Docs-Related File
 
 =head1 SYNOPSIS
 
@@ -17,7 +17,9 @@ methods to do with POD and file type.
 
 It's used by the documentation tools in F<tools/docs>.
 
-=over
+=head2 Class Methods
+
+=over 4
 
 =cut
 
@@ -29,7 +31,6 @@ use Parrot::IO::File;
 @Parrot::Docs::File::ISA = qw(Parrot::IO::File);
 
 use Pod::Simple::Checker;
-#use Pod::Simple::HTML;
 use Parrot::Docs::POD2HTML;
 
 my $UNDEFINED = 'Undefined';
@@ -160,6 +161,12 @@ sub type_for_name
 	return $UNDEFINED;
 }
 
+=back
+
+=head2 Instance Methods
+
+=over 4
+
 =item C<type()>
 
 This first tries to find a type for the file's suffix, failing that it
@@ -279,7 +286,7 @@ sub pod_errors
 
 =item C<pod_as_html()>
 
-Runs C<Pod::Simple::HTML> on the contents of the file. Executable files
+Runs C<Parrot::Docs::POD2HTML> on the contents of the file. Executable files
 are assumed not to contain POD and therefore not formatted.
 
 =cut
@@ -427,7 +434,15 @@ sub short_description
 
 =head1 SEE ALSO
 
-C<Parrot::Docs::Directory>, C<Pod::Simple::Checker>, C<Pod::Simple::HTML>.
+=over 4
+
+=item C<Parrot::Docs::Directory>
+
+=item C<Parrot::Docs::POD2HTML>
+
+=item C<Pod::Simple::Checker>
+
+=back
 
 =cut
 

lib/Parrot/Docs/Group.pm

@@ -8,18 +8,15 @@ Parrot::Docs::Group - Group of documentation items
 =head1 SYNOPSIS
 
 	use Parrot::Docs::Group;
-	
-	my $group = Parrot::Docs::Group->new('Usual suspects', '',
-	    Parrot::Docs::Item->new('', 'foo'),
-	    Parrot::Docs::Item->new('', 'bar'));
 
 =head1 DESCRIPTION
 
-A group is a number of items with some optional descriptive text.
+A documentation I<group> is a number of items with some optional
+descriptive text.
 
-This is a subclass of C<Parrot::Docs::Item>.
+C<Parrot::Docs::Group> is a subclass of C<Parrot::Docs::Item>.
 
-=head2 Methods
+=head2 Class Methods
 
 =over
 
@@ -36,7 +33,8 @@ use Parrot::Docs::Item;
 
 Returns a new group.
 
-Use this when creating groups in a subclass's C<new()> method.
+Use this when creating groups within a C<Parrot::Docs::Section>
+subclass's C<new()> method.
 
 =cut
 
@@ -72,6 +70,12 @@ sub new
 	return $self;
 }
 
+=back
+
+=head2 Instance Methods
+
+=over 4
+
 =item C<name()>
 
 Returns the name of the group.
@@ -137,9 +141,9 @@ Some HTML-formatted text describing the files linked to is returned.
 sub write_contents_html
 {
 	my $self = shift;
-	my $source = shift;
-	my $target = shift;
-	my $silent = shift;
+    my $source = shift || die "No source\n";
+    my $target = shift || die "No target\n";
+    my $silent = shift || 0;
 	my $index_html = '';
 
 	print "\n\n", $self->name unless $silent;
@@ -199,7 +203,13 @@ sub contents_relative_to_source
 
 =head1 SEE ALSO
 
-C<Parrot::Docs::Section>, C<Parrot::Docs::Item>.
+=over 4
+
+=item C<Parrot::Docs::Section>
+
+=item C<Parrot::Docs::Item>
+
+=back
 
 =cut
 

lib/Parrot/Docs/HTMLPage.pm

@@ -3,15 +3,18 @@
 
 =head1 NAME
 
-Parrot::Docs::HTMLPage - HTML Docmentation Page
+Parrot::Docs::HTMLPage - HTML Documentation Page
 
 =head1 DESCRIPTION
 
-This just provides a C<header()> and C<footer()> method for now, to 
-prevent code being duplicated int C<Parrot::Docs::POD2HTML> and 
+C<Parrot::Docs::HTMLPage> gives Parrot documentation pages the Parrot
+house-style.
+
+This just provides C<header()> and C<footer()> class methods for now, to
+prevent code being duplicated in C<Parrot::Docs::POD2HTML> and
 C<Parrot::Docs::Section>.
 
-=head2 Methods
+=head2 Class Methods
 
 =over
 

lib/Parrot/Docs/Item.pm

@@ -3,17 +3,16 @@
 
 =head1 NAME
 
-Parrot::Docs::Item - Docmentation item
+Parrot::Docs::Item - Documentation item
 
 =head1 SYNOPSIS
 
 	use Parrot::Docs::Item;
-	
-	my $item = Parrot::Docs::Item->new('Usual suspects', 'foo', 'bar');
 
 =head1 DESCRIPTION
 
-An item is one or more related paths with some optional descriptive text.
+A documentation I<item> is one or more related paths with some optional
+descriptive text.
 
 Directory paths will be expanded to all the file paths within the
 directory and any subdirectories recursively (see the C<files()> method
@@ -23,7 +22,7 @@ If an item has more than one file associated with it, and has no text,
 then an attempt will be made to extract short descriptions from each
 file to place under the file path in the index HTML.
 
-=head2 Methods
+=head2 Class Methods
 
 =over
 
@@ -39,7 +38,8 @@ use Parrot::Docs::POD2HTML;
 
 Returns a new item.
 
-Use this when creating items in a section's C<new()> method.
+Use this when creating items within a C<Parrot::Docs::Section>
+subclass's C<new()> method.
 
 =cut
 
@@ -79,6 +79,13 @@ sub new
 	return $self;
 }
 
+
+=back
+
+=head2 Instance Methods
+
+=over 4
+
 =item C<set_parent($parent)>
 
 =item C<parent()>
@@ -120,6 +127,13 @@ sub html_navigation
 
 =item C<write_html($source, $target, $silent)>
 
+C<$source> is the directory in which the section's contents will be
+looked for.
+
+C<$target> is directory into which the section's output will be written.
+
+If C<$silent> is true then progress is not reported.
+
 Any POD-formatted text in the item's files is converted to HTML and
 written to a file in C<$target> and an HTML link is created to it.
 
@@ -133,9 +147,9 @@ Some HTML-formatted text describing the files linked to is returned.
 sub write_html
 {
 	my $self = shift;
-	my $source = shift;
-	my $target = shift;
-	my $silent = shift;
+    my $source = shift || die "No source\n";
+    my $target = shift || die "No target\n";
+    my $silent = shift || 0;
 	my $index_html = '';
 	my @rel_paths = $self->contents_relative_to_source($source);
 	my @short_desc = ();
@@ -265,7 +279,13 @@ sub file_paths_relative_to_source
 
 =head1 SEE ALSO
 
-C<Parrot::Docs::Section>, C<Parrot::Docs::Group>.
+=over 4
+
+=item C<Parrot::Docs::Section>
+
+=item C<Parrot::Docs::Group>
+
+=back
 
 =cut