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.
