8 files changed, 79 insertions, 74 deletions
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