[dpkg] 71/187: Dpkg: Document the behavior for consecutive calls to parse() methods

[Reiner Herrmann]

This is an automated email from the git hooks/post-receive script.

deki-guest pushed a commit to branch master
in repository dpkg.

commit 29df37ac73cc130e53bfc4278db9ea912d488ca9
Author: Guillem Jover <guillem at debian.org>
Date:   Mon Aug 15 23:12:43 2016 +0200

    Dpkg: Document the behavior for consecutive calls to parse() methods
    
    Prompted-by: Johannes Schauer <josch at debian.org>
---
 debian/changelog                    | 2 ++
 scripts/Dpkg/Changelog/Debian.pm    | 6 ++++--
 scripts/Dpkg/Conf.pm                | 5 ++++-
 scripts/Dpkg/Control/HashCore.pm    | 4 +++-
 scripts/Dpkg/Control/Info.pm        | 4 ++--
 scripts/Dpkg/Control/Tests/Entry.pm | 5 ++++-
 scripts/Dpkg/Index.pm               | 6 ++++--
 7 files changed, 23 insertions(+), 9 deletions(-)

diff --git a/debian/changelog b/debian/changelog
index 9e61642..573787c 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 at debian.org>.
+    - Document the behavior for consecutive calls to Dpkg perl module parse()
+      methods. Prompted by Johannes Schauer <josch at 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 73a6ddd..4ed04a9 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 111114c..de0513f 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 0600698..46e3dfd 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 5961c99..a5eae87 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 392493c..92eea49 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 86c1bb2..4b125c1 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
 

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/reproducible/dpkg.git