Pod coverage for Perl modules.

[Ralf Wildenhues]

Fairly trivial typing/copying exercise, fixes a few markup errors
and renames a few internal methods.  I'll be pushing this soon.

Cheers,
Ralf

    Pod coverage for Perl modules.
    
    * lib/Automake/ChannelDefs.pm (parse_warnings): Fix
    typo in Pod documentation.
    * lib/Automake/Condition.pm: Add a couple of missing `=back'
    lines.
    (_has): Renamed from ...
    (has): ... this, as this is an internal method.
    (strip, false, true_when): Adjust callers.
    * lib/Automake/Configure_ac.pm: Add Pod `Functions' section with
    documentation for find_configure_ac and require_configure_ac.
    * lib/Automake/Location.pm: Fix typo in Pod.  Add `Methods'
    section, document methods.
    * lib/Automake/RuleDef.pm: New `Methods' Pod section.
    * lib/Automake/VarDef.pm: Document `raw_value'.
    * lib/Automake/Wrap.pm (_tab_length): Rename from ...
    (tab_length): ... this, as this is an internal method.
    (wrap): Adjust callers.
    * lib/Automake/XFile.pm: Reorganize Pod a bit, add `Methods'
    section.

diff --git a/lib/Automake/ChannelDefs.pm b/lib/Automake/ChannelDefs.pm
index a740603..ce6bf29 100644
--- a/lib/Automake/ChannelDefs.pm
+++ b/lib/Automake/ChannelDefs.pm
@@ -1,4 +1,5 @@
-# Copyright (C) 2002, 2003, 2006, 2008, 2009 Free Software Foundation, Inc.
+# Copyright (C) 2002, 2003, 2006, 2008, 2009 Free Software Foundation,
+# Inc.
 
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -43,7 +44,7 @@ Automake::ChannelDefs - channel definitions for Automake and 
helper functions
   verb ($MESSAGE, [%OPTIONS]);
   switch_warning ($CATEGORY);
   parse_WARNINGS ();
-  parse_warning ($OPTION, $ARGUMENT);
+  parse_warnings ($OPTION, $ARGUMENT);
   Automake::ChannelDefs::set_strictness ($STRICTNESS_NAME);
 
 =head1 DESCRIPTION
@@ -307,7 +308,7 @@ sub parse_WARNINGS ()
     }
 }
 
-=item C<parse_warning ($OPTION, $ARGUMENT)>
+=item C<parse_warnings ($OPTION, $ARGUMENT)>
 
 Parse the argument of C<--warning=CATEGORY> or C<-WCATEGORY>.
 
diff --git a/lib/Automake/Condition.pm b/lib/Automake/Condition.pm
index 2d649f6..276c04a 100644
--- a/lib/Automake/Condition.pm
+++ b/lib/Automake/Condition.pm
@@ -1,4 +1,4 @@
-# Copyright (C) 1997, 2001, 2002, 2003, 2006, 2008  Free Software
+# Copyright (C) 1997, 2001, 2002, 2003, 2006, 2008, 2009  Free Software
 # Foundation, Inc.
 
 # This program is free software; you can redistribute it and/or modify
@@ -250,7 +250,7 @@ except those of C<$minuscond>.  This is the opposite of 
C<merge>.
 sub strip ($$)
 {
   my ($self, $minus) = @_;
-  my @res = grep { not $minus->has ($_) } $self->conds;
+  my @res = grep { not $minus->_has ($_) } $self->conds;
   return new Automake::Condition @res;
 }
 
@@ -274,7 +274,7 @@ sub conds ($ )
 }
 
 # Undocumented, shouldn't be needed outside of this class.
-sub has ($$)
+sub _has ($$)
 {
   my ($self, $cond) = @_;
   return exists $self->{'hash'}{$cond};
@@ -289,7 +289,7 @@ Return 1 iff this condition is always false.
 sub false ($ )
 {
   my ($self) = @_;
-  return $self->has ('FALSE');
+  return $self->_has ('FALSE');
 }
 
 =item C<$cond-E<gt>true>
@@ -426,7 +426,7 @@ sub true_when ($$)
   # exists in $WHEN.
   foreach my $cond ($self->conds)
     {
-      return 0 unless $when->has ($cond);
+      return 0 unless $when->_has ($cond);
     }
   return 1;
 }
@@ -518,6 +518,8 @@ sub multiply ($@)
   return (values %res);
 }
 
+=back
+
 =head2 Other helper functions
 
 =over 4
@@ -615,6 +617,8 @@ sub conditional_negate ($)
   return $cond;
 }
 
+=back
+
 =head1 SEE ALSO
 
 L<Automake::DisjConditions>.
diff --git a/lib/Automake/Configure_ac.pm b/lib/Automake/Configure_ac.pm
index 646fad3..d5ad977 100644
--- a/lib/Automake/Configure_ac.pm
+++ b/lib/Automake/Configure_ac.pm
@@ -1,4 +1,4 @@
-# Copyright (C) 2003, 2005, 2006  Free Software Foundation, Inc.
+# Copyright (C) 2003, 2005, 2006, 2009  Free Software Foundation, Inc.
 
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -49,6 +49,20 @@ Automake::Configure_ac - Locate configure.ac or configure.in.
   my $file_name = find_configure_ac ($dir);
   my $file_name = require_configure_ac ($dir);
 
+=over 4
+
+=back
+
+=head2 Functions
+
+=over 4
+
+=item C<$configure_ac = find_configure_ac ([$directory])>
+
+Find a F<configure.ac> or F<configure.in> file in C<$directory>,
+defaulting to the current directory.  Complain if both files are present.
+Return the name of the file found, or the former if neither is present.
+
 =cut
 
 sub find_configure_ac (;@)
@@ -78,6 +92,12 @@ sub find_configure_ac (;@)
 }
 
 
+=item C<$configure_ac = require_configure_ac ([$directory])>
+
+Like C<find_configure_ac>, but fail if neither is present.
+
+=cut
+
 sub require_configure_ac (;$)
 {
   my $res = find_configure_ac (@_);
diff --git a/lib/Automake/Location.pm b/lib/Automake/Location.pm
index 613dc80..1dc81dc 100644
--- a/lib/Automake/Location.pm
+++ b/lib/Automake/Location.pm
@@ -1,4 +1,4 @@
-# Copyright (C) 2002, 2003, 2008  Free Software Foundation, Inc.
+# Copyright (C) 2002, 2003, 2008, 2009  Free Software Foundation, Inc.
 
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -50,7 +50,7 @@ Automake::Location - a class for location tracking, with a 
stack of contexts
       ...
     }
 
-  # Pop a context, and reset the location from the previous context.
+  # Pop a context, and reset the location to the previous context.
   $where->pop_context;
 
   # Clone a Location.  Use this when storing the state of a location
@@ -84,6 +84,16 @@ You can pass a C<Location> to C<Automake::Channels::msg>.
 
 =cut
 
+=head2 Methods
+
+=over
+
+=item C<$where = new Automake::Location ([$position])>
+
+Create and return a new Location object.
+
+=cut
+
 sub new ($;$)
 {
   my ($class, $position) = @_;
@@ -95,18 +105,36 @@ sub new ($;$)
   return $self;
 }
 
+=item C<$location-E<gt>set ($position)>
+
+Change the location to be C<$position>.
+
+=cut
+
 sub set ($$)
 {
   my ($self, $position) = @_;
   $self->{'position'} = $position;
 }
 
+=item C<$location-E<gt>get>
+
+Get the location (without context).
+
+=cut
+
 sub get ($)
 {
   my ($self) = @_;
   return $self->{'position'};
 }
 
+=item C<$location-E<gt>push_context ($context)>
+
+Push a context to the location.
+
+=cut
+
 sub push_context ($$)
 {
   my ($self, $context) = @_;
@@ -114,6 +142,12 @@ sub push_context ($$)
   $self->set (undef);
 }
 
+=item C<$where = $location-E<gt>pop_context ($context)>
+
+Pop a context, and reset the location to the previous context.
+
+=cut
+
 sub pop_context ($)
 {
   my ($self) = @_;
@@ -122,12 +156,25 @@ sub pop_context ($)
   return @{$pair};
 }
 
+=item C<@contexts = $location-E<gt>get_contexts>
+
+Return the array of contexts.
+
+=cut
+
 sub get_contexts ($)
 {
   my ($self) = @_;
   return @{$self->{'contexts'}};
 }
 
+=item C<$location = $location-E<gt>clone>
+
+Clone a Location.  Use this when storing the state of a location
+that would otherwise be modified.
+
+=cut
+
 sub clone ($)
 {
   my ($self) = @_;
@@ -140,6 +187,12 @@ sub clone ($)
   return $other;
 }
 
+=item C<$res = $location-E<gt>dump>
+
+Print the location and the stack of context (for debugging).
+
+=cut
+
 sub dump ($)
 {
   my ($self) = @_;
@@ -152,6 +205,13 @@ sub dump ($)
   return $res;
 }
 
+=item C<@array = $location-E<gt>serialize>
+
+Serialize a Location object (for passing through a thread queue,
+for example).
+
+=cut
+
 sub serialize ($)
 {
   my ($self) = @_;
@@ -166,6 +226,12 @@ sub serialize ($)
   return @serial;
 }
 
+=item C<new Automake::Location::deserialize ($queue)>
+
+De-serialize: recreate a Location object from a queue.
+
+=cut
+
 sub deserialize ($)
 {
   my ($queue) = @_;
@@ -179,6 +245,8 @@ sub deserialize ($)
   return $self;
 }
 
+=back
+
 =head1 SEE ALSO
 
 L<Automake::Channels>
diff --git a/lib/Automake/RuleDef.pm b/lib/Automake/RuleDef.pm
index 20bc106..3bd506d 100644
--- a/lib/Automake/RuleDef.pm
+++ b/lib/Automake/RuleDef.pm
@@ -1,4 +1,4 @@
-# Copyright (C) 2003  Free Software Foundation, Inc.
+# Copyright (C) 2003, 2009  Free Software Foundation, Inc.
 
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -36,6 +36,7 @@ Automake::RuleDef - a class for rule definitions
 =head1 DESCRIPTION
 
 This class gathers data related to one Makefile-rule definition.
+It shouldn't be needed outside of F<Rule.pm>.
 
 =head2 Constants
 
@@ -50,6 +51,20 @@ Possible owners for rules.
 use constant RULE_AUTOMAKE => 0; # Rule defined by Automake.
 use constant RULE_USER => 1;     # Rule defined in the user's Makefile.am.
 
+=back
+
+=head2 Methods
+
+=over 4
+
+=item C<new Automake::RuleDef ($name, $comment, $location, $owner, $source)>
+
+Create a new rule definition with target C<$name>, with associated comment
+C<$comment>, Location C<$location> and owner C<$owner>, defined in file
+C<$source>.
+
+=cut
+
 sub new ($$$$$)
 {
   my ($class, $name, $comment, $location, $owner, $source) = @_;
@@ -60,12 +75,24 @@ sub new ($$$$$)
   return $self;
 }
 
+=item C<$source = $rule-E<gt>source>
+
+Return the source of the rule.
+
+=cut
+
 sub source ($)
 {
   my ($self) = @_;
   return $self->{'source'};
 }
 
+=item C<$name = $rule-E<gt>name>
+
+Return the name of the rule.
+
+=cut
+
 sub name ($)
 {
   my ($self) = @_;
diff --git a/lib/Automake/VarDef.pm b/lib/Automake/VarDef.pm
index d7ba155..7d10bb6 100644
--- a/lib/Automake/VarDef.pm
+++ b/lib/Automake/VarDef.pm
@@ -1,4 +1,4 @@
-# Copyright (C) 2003, 2004, 2006  Free Software Foundation, Inc.
+# Copyright (C) 2003, 2004, 2006, 2009  Free Software Foundation, Inc.
 
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -204,6 +204,8 @@ sub append ($$$)
 
 =item C<$def-E<gt>value>
 
+=item C<$def-E<gt>raw_value>
+
 =item C<$def-E<gt>type>
 
 =item C<$def-E<gt>pretty>
diff --git a/lib/Automake/Wrap.pm b/lib/Automake/Wrap.pm
index 09a135a..ad1d81e 100644
--- a/lib/Automake/Wrap.pm
+++ b/lib/Automake/Wrap.pm
@@ -1,4 +1,4 @@
-# Copyright (C) 2003, 2006  Free Software Foundation, Inc.
+# Copyright (C) 2003, 2006, 2009  Free Software Foundation, Inc.
 
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -48,10 +48,10 @@ maximum length allowed.  (Ticket #17141, fixed in Perl 
5.8.0.)
 
 =cut
 
-# tab_length ($TXT)
-# -----------------
+# _tab_length ($TXT)
+# ------------------
 # Compute the length of TXT, counting tab characters as 8 characters.
-sub tab_length($)
+sub _tab_length($)
 {
   my ($txt) = @_;
   my $len = length ($txt);
@@ -78,16 +78,16 @@ sub wrap($$$$@)
   my ($head, $fill, $eol, $max_len, @values) = @_;
 
   my $result = $head;
-  my $column = tab_length ($head);
+  my $column = _tab_length ($head);
 
-  my $fill_len = tab_length ($fill);
-  my $eol_len = tab_length ($eol);
+  my $fill_len = _tab_length ($fill);
+  my $eol_len = _tab_length ($eol);
 
   my $not_first_word = 0;
 
   foreach (@values)
     {
-      my $len = tab_length ($_);
+      my $len = _tab_length ($_);
 
       # See if the new variable fits on this line.
       # (The + 1 is for the space we add in front of the value.).
diff --git a/lib/Automake/XFile.pm b/lib/Automake/XFile.pm
index f99a00a..b67e251 100644
--- a/lib/Automake/XFile.pm
+++ b/lib/Automake/XFile.pm
@@ -68,18 +68,6 @@ methods C<close>, C<lock> (corresponding to C<flock>), 
C<new>,
 C<open>, C<seek>, and C<truncate>.  It also overrides the C<getline>
 and C<getlines> methods to translate C<\r\n> to C<\n>.
 
-=head1 SEE ALSO
-
-L<perlfunc>,
-L<perlop/"I/O Operators">,
-L<IO::File>
-L<IO::Handle>
-L<IO::Seekable>
-
-=head1 HISTORY
-
-Derived from IO::File.pm by Akim Demaille E<lt>F<address@hidden>E<gt>.
-
 =cut
 
 require 5.000;
@@ -113,9 +101,16 @@ eval {
 # Used in croak error messages.
 my $me = basename ($0);
 
-################################################
-## Constructor
-##
+=head2 Methods
+
+=over
+
+=item C<$fh = new Automake::XFile ([$expr, ...]>
+
+Constructor a new XFile object.  Additional arguments
+are passed to C<open>, if any.
+
+=cut
 
 sub new
 {
@@ -129,9 +124,12 @@ sub new
   $fh;
 }
 
-################################################
-## Open
-##
+=item C<$fh-E<gt>open ([$file, ...])>
+
+Open a file, passing C<$file> and further arguments to C<IO::File::open>.
+Die if opening fails.  Store the name of the file.  Use binmode for writing.
+
+=cut
 
 sub open
 {
@@ -156,9 +154,11 @@ sub open
   binmode $fh if $file =~ /^\s*>/;
 }
 
-################################################
-## Close
-##
+=item C<$fh-E<gt>close>
+
+Close the file, handling errors.
+
+=cut
 
 sub close
 {
@@ -172,9 +172,12 @@ sub close
     }
 }
 
-################################################
-## Getline
-##
+=item C<$line = $fh-E<gt>getline>
+
+Read and return a line from the file.  Ensure C<\r\n> is translated to
+C<\n> on input files.
+
+=cut
 
 # Some Win32/perl installations fail to translate \r\n to \n on input
 # so we do that here.
@@ -187,9 +190,11 @@ sub getline
   return $_;
 }
 
-################################################
-## Getlines
-##
+=item C<@lines = $fh-E<gt>getlines>
+
+Slurp lines from the files.
+
+=cut
 
 sub getlines
 {
@@ -199,9 +204,11 @@ sub getlines
   return @res;
 }
 
-################################################
-## Name
-##
+=item C<$name = $fh-E<gt>name>
+
+Return the name of the file.
+
+=cut
 
 sub name
 {
@@ -209,9 +216,13 @@ sub name
   return ${*$fh}{'autom4te_xfile_file'};
 }
 
-################################################
-## Lock
-##
+=item C<$fh-E<gt>lock>
+
+Lock the file using C<flock>.  If locking fails for reasons other than
+C<flock> being unsupported, then error out if C<$ENV{'MAKEFLAGS'}> indicates
+that we are spawned from a parallel C<make>.
+
+=cut
 
 sub lock
 {
@@ -243,9 +254,11 @@ sub lock
     }
 }
 
-################################################
-## Seek
-##
+=item C<$fh-E<gt>seek ($position, [$whence])>
+
+Seek file to C<$position>.  Die if seeking fails.
+
+=cut
 
 sub seek
 {
@@ -258,9 +271,11 @@ sub seek
     }
 }
 
-################################################
-## Truncate
-##
+=item C<$fh-E<gt>truncate ($len)>
+
+Truncate the file to length C<$len>.  Die on failure.
+
+=cut
 
 sub truncate
 {
@@ -272,6 +287,22 @@ sub truncate
     }
 }
 
+=back
+
+=head1 SEE ALSO
+
+L<perlfunc>,
+L<perlop/"I/O Operators">,
+L<IO::File>
+L<IO::Handle>
+L<IO::Seekable>
+
+=head1 HISTORY
+
+Derived from IO::File.pm by Akim Demaille E<lt>F<address@hidden>E<gt>.
+
+=cut
+
 1;
 
 ### Setup "GNU" style for perl-mode and cperl-mode.