Hi!
On Sat, 2019-11-02 at 16:31:24 +0100, intrigeri wrote:
> Guillem Jover:
> > On Sat, 2019-07-27 at 12:20:00 -0300, intrigeri wrote:
> >> Oh, this is very interesting, thanks! I had taken a look at that
> >> module, but from the documentation I understood it only gives us "the
> >> number of changelog entries that have been parsed with success", so
> >> I had discarded this option.
>
> > If the documantion was not clear, I'd be happy to try to improve it so
> > that other people do not get this impression too. Could you cover a bit
> > what lead you to that conclusion?
>
> Back then I had read only `perldoc Dpkg::Changelog::Debian`, which
> documents one method:
>
> $c->parse($fh, $description)
> 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.
>
> I understood only later that "See also: Dpkg::Changelog" was not
> optional :)
Ah! Thanks for the info. How about the following clarification then? :)
Regards,
Guillem
diff --git i/scripts/Dpkg/Changelog/Debian.pm w/scripts/Dpkg/Changelog/Debian.pm
index 937acb5e0..a85f3af12 100644
--- i/scripts/Dpkg/Changelog/Debian.pm
+++ w/scripts/Dpkg/Changelog/Debian.pm
@@ -24,6 +24,12 @@ Dpkg::Changelog::Debian - parse Debian changelogs
=head1 DESCRIPTION
+This class represents a Debian changelog file as an array of changelog
+entries (Dpkg::Changelog::Entry::Debian).
+It implements the generic interface Dpkg::Changelog.
+Only methods specific to this implementation are described below,
+the rest are inherited.
+
Dpkg::Changelog::Debian parses Debian changelogs as described in
deb-changelog(5).
@@ -118,10 +124,11 @@ my $ancient_delimiter_re = qr{
=over 4
-=item $c->parse($fh, $description)
+=item $count = $c->parse($fh, $description)
-Read the filehandle and parse a Debian changelog in it. The data in the
-object is reset before parsing new data.
+Read the filehandle and parse a Debian changelog in it, to store the entries
+as an array of Dpkg::Changelog::Entry::Debian objects.
+Any previous entries in the object are reset before parsing new data.
Returns the number of changelog entries that have been parsed with success.
diff --git i/scripts/Dpkg/Changelog/Entry.pm w/scripts/Dpkg/Changelog/Entry.pm
index 144dacb0f..d6ce55601 100644
--- i/scripts/Dpkg/Changelog/Entry.pm
+++ w/scripts/Dpkg/Changelog/Entry.pm
@@ -39,7 +39,7 @@ Dpkg::Changelog::Entry - represents a changelog entry
=head1 DESCRIPTION
-This object represents a changelog entry. It is composed
+This class represents a changelog entry. It is composed
of a set of lines with specific purpose: an header line, changes lines, a
trailer line. Blank lines can be between those kind of lines.
diff --git i/scripts/Dpkg/Changelog/Entry/Debian.pm w/scripts/Dpkg/Changelog/Entry/Debian.pm
index defa3b0b6..04bf8ef04 100644
--- i/scripts/Dpkg/Changelog/Entry/Debian.pm
+++ w/scripts/Dpkg/Changelog/Entry/Debian.pm
@@ -47,9 +47,10 @@ Dpkg::Changelog::Entry::Debian - represents a Debian changelog entry
=head1 DESCRIPTION
-This object represents a Debian changelog entry. It implements the
-generic interface Dpkg::Changelog::Entry. Only functions specific to this
-implementation are described below.
+This class represents a Debian changelog entry.
+It implements the generic interface Dpkg::Changelog::Entry.
+Only functions specific to this implementation are described below,
+the rest are inherited.
=cut
diff --git i/scripts/Dpkg/Control/Changelog.pm w/scripts/Dpkg/Control/Changelog.pm
index 1f65127c4..9184cedbc 100644
--- i/scripts/Dpkg/Control/Changelog.pm
+++ w/scripts/Dpkg/Control/Changelog.pm
@@ -32,7 +32,7 @@ Dpkg::Control::Changelog - represent info fields output by dpkg-parsechangelog
=head1 DESCRIPTION
-This object derives directly from Dpkg::Control with the type
+This class derives directly from Dpkg::Control with the type
CTRL_CHANGELOG.
=head1 METHODS
