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

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

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.

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
 

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
 

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
 

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
 

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
 

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