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<a...@freefriends.org>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<a...@freefriends.org>E<gt>. + +=cut + 1; ### Setup "GNU" style for perl-mode and cperl-mode.