Dpkg: Document the behavior for consecutive calls to parse() methods

Prompted-by: Johannes Schauer <josch@debian.org>

7 files changed, 23 insertions, 9 deletions

diff --git a/debian/changelog b/debian/changelog
index 9e61642af..573787c18 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -68,6 +68,8 @@ dpkg (1.18.11) UNRELEASED; urgency=medium
       instead of assuming that every page has the SEE ALSO section.
     - Explicitly mention that Dpkg::Checksums::add_from_file() is used to
       verify digests too. Prompted by Johannes Schauer <josch@debian.org>.
+    - Document the behavior for consecutive calls to Dpkg perl module parse()
+      methods. Prompted by Johannes Schauer <josch@debian.org>.
   * Build system:
     - Add support for profiling perl modules.
     - Clean up compiler and linker automatic flag usage in configure.
diff --git a/scripts/Dpkg/Changelog/Debian.pm b/scripts/Dpkg/Changelog/Debian.pm
index 73a6dddfa..4ed04a943 100644
--- a/scripts/Dpkg/Changelog/Debian.pm
+++ b/scripts/Dpkg/Changelog/Debian.pm
@@ -120,8 +120,10 @@ my $ancient_delimiter_re = qr{
 
 =item $c->parse($fh, $description)
 
-Read the filehandle and parse a Debian changelog in it. Returns the number
-of changelog entries that have been parsed with success.
+Read the filehandle and parse a Debian changelog in it. The data in the
+object is reset before parsing new data.
+
+Returns the number of changelog entries that have been parsed with success.
 
 =cut
 
diff --git a/scripts/Dpkg/Conf.pm b/scripts/Dpkg/Conf.pm
index 111114c8b..de0513f11 100644
--- a/scripts/Dpkg/Conf.pm
+++ b/scripts/Dpkg/Conf.pm
@@ -157,7 +157,10 @@ sub load_config {
 
 =item $conf->parse($fh)
 
-Parse options from a file handle. Return the number of options parsed.
+Parse options from a file handle. When called multiple times, the parsed
+options are accumulated.
+
+Return the number of options parsed.
 
 =cut
 
diff --git a/scripts/Dpkg/Control/HashCore.pm b/scripts/Dpkg/Control/HashCore.pm
index 06006981f..46e3dfddd 100644
--- a/scripts/Dpkg/Control/HashCore.pm
+++ b/scripts/Dpkg/Control/HashCore.pm
@@ -183,7 +183,9 @@ sub parse_error {
 Parse a control file from the given filehandle. Exits in case of errors.
 $description is used to describe the filehandle, ideally it's a filename
 or a description of where the data comes from. It's used in error
-messages. Returns true if some fields have been parsed.
+messages. When called multiple times, the parsed fields are accumulated.
+
+Returns true if some fields have been parsed.
 
 =cut
 
diff --git a/scripts/Dpkg/Control/Info.pm b/scripts/Dpkg/Control/Info.pm
index 5961c9915..a5eae8732 100644
--- a/scripts/Dpkg/Control/Info.pm
+++ b/scripts/Dpkg/Control/Info.pm
@@ -99,8 +99,8 @@ loads from the standard input.
 
 Parse a control file from the given filehandle. Exits in case of errors.
 $description is used to describe the filehandle, ideally it's a filename
-or a description of where the data comes from. It's used in error
-messages.
+or a description of where the data comes from. It is used in error messages.
+The data in the object is reset before parsing new control files.
 
 =cut
 
diff --git a/scripts/Dpkg/Control/Tests/Entry.pm b/scripts/Dpkg/Control/Tests/Entry.pm
index 392493c2a..92eea49f4 100644
--- a/scripts/Dpkg/Control/Tests/Entry.pm
+++ b/scripts/Dpkg/Control/Tests/Entry.pm
@@ -61,7 +61,10 @@ sub new {
 
 =item $entry->parse($fh, $desc)
 
-Parse a control test entry from a filehandle.
+Parse a control test entry from a filehandle. When called multiple times,
+the parsed fields are accumulated.
+
+Returns true if parsing was a success.
 
 =cut
 
diff --git a/scripts/Dpkg/Index.pm b/scripts/Dpkg/Index.pm
index 86c1bb2e5..4b125c1fa 100644
--- a/scripts/Dpkg/Index.pm
+++ b/scripts/Dpkg/Index.pm
@@ -169,8 +169,10 @@ parsed. Handles compressed files transparently based on their extensions.
 
 =item $index->parse($fh, $desc)
 
-Reads the filehandle and creates all items parsed. Returns the number of
-items parsed.
+Reads the filehandle and creates all items parsed. When called multiple
+times, the parsed stanzas are accumulated.
+
+Returns the number of items parsed.
 
 =cut