This is an automated email from the git hooks/post-receive script. guillem pushed a commit to branch master in repository dpkg.
View the commit online: https://git.dpkg.org/cgit/dpkg/dpkg.git/commit/?id=853f59ec0468f72fa29811a8fe48fad91fab6083 commit 853f59ec0468f72fa29811a8fe48fad91fab6083 Author: Guillem Jover <guil...@debian.org> AuthorDate: Tue Oct 23 02:58:56 2018 +0200 perl: Fix POD for Dpkg::Interface::Storable derived method implementations Document inherited methods. Document the return values. Note which arguments are optional. Reorder methods by their position in the stack. --- debian/changelog | 1 + scripts/Dpkg/Changelog.pm | 18 +++++++----------- scripts/Dpkg/Conf.pm | 10 +++++----- scripts/Dpkg/Control/HashCore.pm | 19 +++++++++---------- scripts/Dpkg/Control/Info.pm | 15 ++++++++------- scripts/Dpkg/Deps/Simple.pm | 38 ++++++++++++++++++++++++-------------- scripts/Dpkg/Index.pm | 25 ++++++++++++------------- scripts/Dpkg/Interface/Storable.pm | 4 ++-- scripts/Dpkg/Substvars.pm | 24 ++++++++++++------------ 9 files changed, 80 insertions(+), 74 deletions(-) diff --git a/debian/changelog b/debian/changelog index 7e5ea0e24..1178f6240 100644 --- a/debian/changelog +++ b/debian/changelog @@ -16,6 +16,7 @@ dpkg (1.19.3) UNRELEASED; urgency=medium - dpkg-query(1): Document the version introducing the -f option. - dpkg-architecture(1): Add reference to the TERMS section in the VARIABLES section. Prompted by Axel Beckert <a...@debian.org>. + - Fix POD for Dpkg::Interface::Storable derived method implementations. * Code internals: - dpkg-maintscript-helper: Use an explicit escape instead of a literal backslash. diff --git a/scripts/Dpkg/Changelog.pm b/scripts/Dpkg/Changelog.pm index 39353fb5c..47752b911 100644 --- a/scripts/Dpkg/Changelog.pm +++ b/scripts/Dpkg/Changelog.pm @@ -74,12 +74,6 @@ sub new { return $self; } -=item $c->load($filename) - -Parse $filename as a changelog. - -=cut - =item $c->set_options(%opts) Change the value of some options. "verbose" (defaults to 1) defines @@ -443,11 +437,7 @@ sub abort_early { return; } -=item $c->save($filename) - -Save the changelog in the given file. - -=item $c->output() +=item $str = $c->output() =item "$c" @@ -476,6 +466,12 @@ sub output { return $str; } +=item $c->save($filename) + +Save the changelog in the given file. + +=cut + our ( @URGENCIES, %URGENCIES ); BEGIN { @URGENCIES = qw(low medium high critical emergency); diff --git a/scripts/Dpkg/Conf.pm b/scripts/Dpkg/Conf.pm index ca98cd3a7..5b98bbd8e 100644 --- a/scripts/Dpkg/Conf.pm +++ b/scripts/Dpkg/Conf.pm @@ -221,7 +221,7 @@ sub filter { @{$self->{options}}; } -=item $string = $conf->output($fh) +=item $string = $conf->output([$fh]) Write the options in the given filehandle (if defined) and return a string representation of the content (that would be) written. @@ -230,10 +230,6 @@ representation of the content (that would be) written. Return a string representation of the content. -=item $conf->save($file) - -Save the options in a file. - =cut sub output { @@ -249,6 +245,10 @@ sub output { return $ret; } +=item $conf->save($file) + +Save the options in a file. + =back =head1 CHANGES diff --git a/scripts/Dpkg/Control/HashCore.pm b/scripts/Dpkg/Control/HashCore.pm index e83522729..542069332 100644 --- a/scripts/Dpkg/Control/HashCore.pm +++ b/scripts/Dpkg/Control/HashCore.pm @@ -160,11 +160,6 @@ sub get_option { return $$self->{$k}; } -=item $c->load($file) - -Parse the content of $file. Exits in case of errors. Returns true if some -fields have been parsed. - =item $c->parse_error($file, $fmt, ...) Prints an error message and dies on syntax parse errors. @@ -284,6 +279,11 @@ sub parse { return defined($cf); } +=item $c->load($file) + +Parse the content of $file. Exits in case of errors. Returns true if some +fields have been parsed. + =item $c->find_custom_field($name) Scan the fields and look for a user specific field whose name matches the @@ -313,11 +313,6 @@ sub get_custom_field { return; } -=item $c->save($filename) - -Write the string representation of the control information to a -file. - =item $str = $c->output() =item "$c" @@ -386,6 +381,10 @@ sub output { return $str; } +=item $c->save($filename) + +Write the string representation of the control information to a file. + =item $c->set_output_order(@fields) Define the order in which fields will be displayed in the output() method. diff --git a/scripts/Dpkg/Control/Info.pm b/scripts/Dpkg/Control/Info.pm index a5eae8732..9b07eedbe 100644 --- a/scripts/Dpkg/Control/Info.pm +++ b/scripts/Dpkg/Control/Info.pm @@ -90,11 +90,6 @@ sub reset { $self->{packages} = []; } -=item $c->load($file) - -Load the content of $file. Exits in case of errors. If file is "-", it -loads from the standard input. - =item $c->parse($fh, $description) Parse a control file from the given filehandle. Exits in case of errors. @@ -129,6 +124,11 @@ sub parse { } } +=item $c->load($file) + +Load the content of $file. Exits in case of errors. If file is "-", it +loads from the standard input. + =item $c->[0] =item $c->get_source() @@ -182,9 +182,10 @@ sub get_packages { return @{$self->{packages}}; } -=item $c->output($filehandle) +=item $str = $c->output([$fh]) -Dump the content into a filehandle. +Return the content info into a string. If $fh is specified print it into +the filehandle. =cut diff --git a/scripts/Dpkg/Deps/Simple.pm b/scripts/Dpkg/Deps/Simple.pm index 0557c7cfc..4fa1ae8d5 100644 --- a/scripts/Dpkg/Deps/Simple.pm +++ b/scripts/Dpkg/Deps/Simple.pm @@ -149,20 +149,6 @@ sub reset { $self->{restrictions} = undef; } -=item $dep->parse($fh, $desc) - -Parses a line from a filehandle. - -=cut - -sub parse { - my ($self, $fh, $desc) = @_; - - my $line = <$fh>; - chomp $line; - return $self->parse_string($line); -} - =item $dep->parse_string($dep_string) Parses the dependency string and modifies internal properties to match the @@ -224,6 +210,24 @@ sub parse_string { } } +=item $dep->parse($fh, $desc) + +Parse a dependency line from a filehandle. + +=cut + +sub parse { + my ($self, $fh, $desc) = @_; + + my $line = <$fh>; + chomp $line; + return $self->parse_string($line); +} + +=item $dep->load($filename) + +Parse a dependency line from $filename. + =item $dep->output([$fh]) =item "$dep" @@ -257,6 +261,12 @@ sub output { return $res; } +=item $dep->save($filename) + +Save the dependency into the given $filename. + +=cut + # _arch_is_superset(\@p, \@q) # # Returns true if the arch list @p is a superset of arch list @q. diff --git a/scripts/Dpkg/Index.pm b/scripts/Dpkg/Index.pm index bcee6205b..682f16921 100644 --- a/scripts/Dpkg/Index.pm +++ b/scripts/Dpkg/Index.pm @@ -237,11 +237,6 @@ sub add { $self->{items}{$key} = $item; } -=item $index->load($file) - -Reads the file and creates all items parsed. Returns the number of items -parsed. Handles compressed files transparently based on their extensions. - =item $index->parse($fh, $desc) Reads the filehandle and creates all items parsed. When called multiple @@ -263,10 +258,10 @@ sub parse { return $i; } -=item $index->save($file) +=item $index->load($file) -Writes the content of the index in a file. Auto-compresses files -based on their extensions. +Reads the file and creates all items parsed. Returns the number of items +parsed. Handles compressed files transparently based on their extensions. =item $item = $index->new_item() @@ -404,17 +399,16 @@ sub sort { } } -=item $str = $index->output() +=item $str = $index->output([$fh]) =item "$index" -Get a string representation of the index. The Dpkg::Control objects are +Get a string representation of the index. The L<Dpkg::Control> objects are output in the order which they have been read or added except if the order have been changed with sort(). -=item $index->output($fh) - -Print the string representation of the index to a filehandle. +Print the string representation of the index to a filehandle if $fh has +been passed. =cut @@ -432,6 +426,11 @@ sub output { return $str; } +=item $index->save($file) + +Writes the content of the index in a file. Auto-compresses files +based on their extensions. + =back =head1 CHANGES diff --git a/scripts/Dpkg/Interface/Storable.pm b/scripts/Dpkg/Interface/Storable.pm index eb6078d3b..5ed308cf2 100644 --- a/scripts/Dpkg/Interface/Storable.pm +++ b/scripts/Dpkg/Interface/Storable.pm @@ -48,13 +48,13 @@ from Dpkg::Interface::Storable so that the methods provided can work. =over 4 -=item $obj->parse($fh, $desc) +=item $obj->parse($fh[, $desc]) This methods initialize the object with the data stored in the filehandle. $desc is optional and is a textual description of the filehandle used in error messages. -=item $string = $obj->output($fh) +=item $string = $obj->output([$fh]) This method returns a string representation of the object in $string and it writes the same string to $fh (if it's defined). diff --git a/scripts/Dpkg/Substvars.pm b/scripts/Dpkg/Substvars.pm index 650eae7fa..d2060efc5 100644 --- a/scripts/Dpkg/Substvars.pm +++ b/scripts/Dpkg/Substvars.pm @@ -183,10 +183,6 @@ sub no_warn { $self->mark_as_used($key); } -=item $s->load($file) - -Add new substitutions read from $file. - =item $s->parse($fh, $desc) Add new substitutions read from the filehandle. $desc is used to identify @@ -216,6 +212,10 @@ sub parse { return $count } +=item $s->load($file) + +Add new substitutions read from $file. + =item $s->set_version_substvars($sourceversion, $binaryversion) Defines ${binary:Version}, ${source:Version} and @@ -404,20 +404,15 @@ sub filter { } } -=item $s->save($file) - -Store all substitutions variables except the automatic ones in the -indicated file. - =item "$s" Return a string representation of all substitutions variables except the automatic ones. -=item $str = $s->output($fh) +=item $str = $s->output([$fh]) -Print all substitutions variables except the automatic ones in the -filehandle and return the content written. +Return all substitutions variables except the automatic ones. If $fh +is passed print them into the filehandle. =cut @@ -434,6 +429,11 @@ sub output { return $str; } +=item $s->save($file) + +Store all substitutions variables except the automatic ones in the +indicated file. + =back =head1 CHANGES -- Dpkg.Org's dpkg
