[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

[SCM] Debian package checker branch, master, updated. 2.5.11-41-ge60d760



The following commit has been merged in the master branch:
commit e60d760cbbf956b881598f720d5659e3a9a6c5b1
Author: Niels Thykier <niels@thykier.net>
Date:   Wed Jan 2 12:19:10 2013 +0100

    L::Collect{::*}: Move Needs-Info requirements to POD part
    
    For "public" methods, move the "Needs-Info" requirements to the POD
    description of the method.  At the same time, change the format a bit
    to make it more "consumable" for "non-core" developers.
    
    The old "sub X Needs-Info Y" variant remains in use for "internal"
    methods.
    
    Note that:
    
     * The "diamond" ("<>") has been replaced with the word "none".
       (even for the "old" variant)
    
     * L<.../methodx> are accepted as alternatives to the ":methodx".
       With this it is possible to link to the method in question rather
       than just naming it.
    
    Signed-off-by: Niels Thykier <niels@thykier.net>

diff --git a/doc/tutorial/Lintian/Tutorial/WritingChecks.pod b/doc/tutorial/Lintian/Tutorial/WritingChecks.pod
index 4c70200..21d011a 100644
--- a/doc/tutorial/Lintian/Tutorial/WritingChecks.pod
+++ b/doc/tutorial/Lintian/Tutorial/WritingChecks.pod
@@ -490,19 +490,17 @@ listed in Needs-Info.  See L<Keeping Needs-Info up to date>.
 =head2 Keeping Needs-Info up to date
 
 Keeping the "Needs-Info" field of your I<.desc> file is a bit of
-manual work.  Whenever you use something from an
-L<info|Lintian::Collect> object, find the relevant method in the
-source of that module.  Usually just above the method name (but
-something in the middle of its code) you will find a comment saying:
+manual work.  In the API description for the method there will
+generally be a line looking something like:
 
-  # sub methodx Needs-Info Y
+  Needs-Info requirements for using methodx: Y
 
 Which means generally that the methodx requires Y to work.  Here Y is a
 comma separated list and each element of Y basically falls into 3 cases.
 
 =over 4
 
-=item The element is a diamond (i.e. <>)
+=item * The element is a the word I<none>
 
 In this case, the method has no "external" requirements and can be
 used without any changes to your Needs-Info.  The "field" method
@@ -510,21 +508,26 @@ is an example of this.
 
 This only makes sense if it is the only element in the list.
 
-=item The element is method prefixed with a colon (e.g. ":index")
+=item * The element is a link to a method
 
 In this case, the method uses another method to do is job.  An example
-is the "sorted_index" method, which uses the "index" method.  So using
-"sorted_index" has the same requirements as using "index".
+is the
+L<sorted_control_index|Lintian::Collect::Binary/sorted_control_index>
+method, which uses the
+L<control_index|Lintian::Collect::Binary/control_index (FILE)>
+method.  So using I<sorted_control_index> has the same requirements as
+using I<control_index>.
 
-=item The element is the name of a collection (e.g. "index").
+=item * The element is the name of a collection (e.g. "control_index").
 
 In this case, the method needs the given collection to be run.  So to
-use (e.g.) "index", you have to put "index" in your Needs-Info.
+use (e.g.) L<control_index|Lintian::Collect::Binary/control_index (FILE)>,
+you have to put "bin-pkg-control" in your Needs-Info.
 
 =back
 
 CAVEAT: Methods can have different requirements based on the type of
 package!  Example being "changelog", which requires "changelog-file"
-in binary packages and ":debfiles" in source packages.
+in binary packages and "Same as debfiles" in source packages.
 
 =cut
diff --git a/lib/Lintian/Collect.pm b/lib/Lintian/Collect.pm
index f51b167..9fa290e 100644
--- a/lib/Lintian/Collect.pm
+++ b/lib/Lintian/Collect.pm
@@ -111,9 +111,10 @@ binary / udeb packages and .changes files.
 
 Returns the name of the package.
 
+Needs-Info requirements for using I<name>: none
+
 =cut
 
-# sub name Needs-Info <>
 sub name {
     my ($self) = @_;
     return $self->{name};
@@ -123,9 +124,10 @@ sub name {
 
 Returns the type of the package.
 
+Needs-Info requirements for using I<type>: none
+
 =cut
 
-# sub type Needs-Info <>
 sub type {
     my ($self) = @_;
     return $self->{type};
@@ -135,9 +137,10 @@ sub type {
 
 Returns the base_dir where all the package information is stored.
 
+Needs-Info requirements for using I<base_dir>: none
+
 =cut
 
-# sub base_dir Needs-Info <>
 sub base_dir {
     my ($self) = @_;
     return $self->{base_dir};
@@ -149,9 +152,10 @@ Return the path to the ENTRY in the lab.  This is a convenience method
 around base_dir.  If ENTRY is not given, this method behaves like
 base_dir.
 
+Needs-Info requirements for using I<lab_data_path>: L</base_dir>
+
 =cut
 
-# sub lab_data_path Needs-Info <>
 sub lab_data_path {
     my ($self, $entry) = @_;
     my $base = $self->base_dir;
@@ -180,9 +184,10 @@ Some checks rely on the presence "source"-field to whitelist some
 packages, so removing this behaviour may cause regressions (see
 bug 640186 for an example).
 
+Needs-Info requirements for using I<field>: none
+
 =cut
 
-# sub field Needs-Info <>
 sub field {
     my ($self, $field, $def) = @_;
     return $self->_get_field ($field, $def);
@@ -197,7 +202,7 @@ sub field {
 # return $def (or undef if $def was not given).
 #
 # It must cache the result if possible, since field and fields are called often.
-# sub _get_field Needs-Info <>
+# sub _get_field Needs-Info none
 sub _get_field {
     my ($self, $field, $def) = @_;
     my $fields;
@@ -229,9 +234,9 @@ sub _get_field {
 Returns a truth value if the package appears to be non-free (based on
 the section field; "non-free/*" and "restricted/*")
 
-=cut
+Needs-Info requirements for using I<is_non_free>: L</field ([FIELD[, DEFAULT]])>
 
-# sub is_non_free Needs-Info <>
+=cut
 
 sub is_non_free {
     my ($self) = @_;
diff --git a/lib/Lintian/Collect/Binary.pm b/lib/Lintian/Collect/Binary.pm
index efc2272..f4e2987 100644
--- a/lib/Lintian/Collect/Binary.pm
+++ b/lib/Lintian/Collect/Binary.pm
@@ -92,9 +92,10 @@ Nativeness will be judged by its version number.
 If the version number is absent, this will return false (as
 native packages are a lot rarer than non-native ones).
 
+Needs-Info requirements for using I<native>: L<Same as field|Lintian::Collect/field ([FIELD[, DEFAULT]])>
+
 =cut
 
-# sub native Needs-Info :field
 sub native {
     my ($self) = @_;
     return $self->{native} if exists $self->{native};
@@ -116,13 +117,14 @@ object, or undef if the changelog doesn't exist.  The changelog-file
 collection script must have been run to create the changelog file, which
 this method expects to find in F<changelog>.
 
+Needs-Info requirements for using I<changelog>: changelog-file
+
 =cut
 
 sub changelog {
     my ($self) = @_;
     return $self->{changelog} if exists $self->{changelog};
     my $dch = $self->lab_data_path ('changelog');
-    # sub changelog Needs-Info changelog-file
     if (-l $dch || ! -f $dch) {
         $self->{changelog} = undef;
     } else {
@@ -147,9 +149,10 @@ The caveats of L<unpacked|Lintian::Collect::Package/unpacked ([FILE])>
 also apply to this method.  However, as the control.tar.gz is not
 known to contain symlinks, a simple file type check is usually enough.
 
+Needs-Info requirements for using I<control>: bin-pkg-control
+
 =cut
 
-# sub control Needs-Info bin-pkg-control
 sub control {
     my ($self, $file) = @_;
     return $self->_fetch_extracted_dir('control', 'control', $file);
@@ -166,9 +169,10 @@ To get a list of entries in the control.tar.gz, see
 L</sorted_control_index>.  To actually access the underlying file
 (e.g. the contents), use L</control ([FILE])>.
 
+Needs-Info requirements for using I<control_index>: bin-pkg-control
+
 =cut
 
-# sub control_index Needs-Info bin-pkg-control
 sub control_index {
     my ($self, $file) = @_;
     return $self->_fetch_index_data ('control-index', 'control-index',
@@ -184,9 +188,10 @@ to L</control ([FILE])> or L</control_index (FILE)> as is.
 The array will not contain the entry for the "root" of the
 control.tar.gz.
 
+Needs-Info requirements for using I<sorted_control_index>: L<Same as control_index|/control_index (FILE)>
+
 =cut
 
-# sub sorted_control_index Needs-Info :control_index
 sub sorted_control_index {
     my ($self) = @_;
     # control_index does all our work for us, so call it if
@@ -203,9 +208,10 @@ returns an open read handle with no content.
 
 Caller is responsible for closing the handle either way.
 
+Needs-Info requirements for using I<strings>: strings
+
 =cut
 
-# sub strings Needs-Info strings
 sub strings {
     my ($self, $file) = @_;
     my $real = $self->_fetch_extracted_dir ('strings', 'strings', $file);
@@ -223,9 +229,10 @@ Returns a hashref mapping a FILE to its md5sum.  The md5sum is
 computed by Lintian during extraction and is not guaranteed to match
 the md5sum in the "md5sums" control file.
 
+Needs-Info requirements for using I<md5sums>: md5sums
+
 =cut
 
-#  sub md5sums Needs-Info md5sums
 sub md5sums {
     my ($self) = @_;
     return $self->{md5sums} if exists $self->{md5sums};
@@ -283,6 +290,8 @@ look up this table.
 
 =back
 
+Needs-Info requirements for using I<scripts>: scripts
+
 =cut
 
 sub scripts {
@@ -291,7 +300,6 @@ sub scripts {
     my $scrf = $self->lab_data_path ('scripts');
     my %scripts;
     local $_;
-    # sub scripts Needs-Info scripts
     open SCRIPTS, '<', $scrf
         or fail "cannot open scripts $scrf: $!";
     while (<SCRIPTS>) {
@@ -319,9 +327,10 @@ Returns a hashref mapping a FILE to the data collected by objdump-info
 or C<undef> if no data is available for that FILE.  Data is generally
 only collected for ELF files.
 
+Needs-Info requirements for using I<objdump_info>: objdump-info
+
 =cut
 
-# Returns the information from collect/objdump-info
 sub objdump_info {
     my ($self) = @_;
     return $self->{objdump_info} if exists $self->{objdump_info};
@@ -329,7 +338,6 @@ sub objdump_info {
     my %objdump_info;
     my ($dynsyms, $file);
     local $_;
-    # sub objdump_info Needs-Info objdump-info
     my $fd = open_gz ($objf)
         or fail "cannot open $objf: $!";
     foreach my $pg (parse_dpkg_control ($fd)) {
@@ -400,9 +408,10 @@ Returns a hashref mapping a FILE to its hardening issues.
 NB: This is generally only useful for checks/binaries to emit the
 hardening-no-* tags.
 
+Needs-Info requirements for using I<hardening_info>: hardening-info
+
 =cut
 
-# sub hardening_info Needs-Info hardening-info
 sub hardening_info {
     my ($self) = @_;
     return $self->{hardening_info} if exists $self->{hardening_info};
@@ -455,9 +464,10 @@ is its "Major class version" for Java or "-" if it is not a class file.
 
 =back
 
+Needs-Info requirements for using I<java_info>: java-info
+
 =cut
 
-# sub java_info Needs-Info java-info
 sub java_info {
     my ($self) = @_;
     return $self->{java_info} if exists $self->{java_info};
@@ -508,7 +518,7 @@ sub java_info {
 
 =item relation (FIELD)
 
-Returns a Lintian::Relation object for the specified FIELD, which should
+Returns a L<Lintian::Relation> object for the specified FIELD, which should
 be one of the possible relationship fields of a Debian package or one of
 the following special values:
 
@@ -531,9 +541,10 @@ The concatenation of Recommends and Suggests.
 If FIELD isn't present in the package, the returned Lintian::Relation
 object will be empty (always satisfied and implies nothing).
 
+Needs-Info requirements for using I<relation>: L<Same as field|Lintian::Collect/field ([FIELD[, DEFAULT]])>
+
 =cut
 
-# sub relation Needs-Info :field
 sub relation {
     my ($self, $field) = @_;
     $field = lc $field;
@@ -586,9 +597,9 @@ Guessed from package description, section or package name.
 
 =back
 
-=cut
+Needs-Info requirements for using I<is_pkg_class>: L<Same as field|Lintian::Collect/field ([FIELD[, DEFAULT]])>
 
-# sub is_pkg_class Needs-Info :field
+=cut
 
 {
     # Regexes to try against the package description to find metapackages or
@@ -621,9 +632,10 @@ Note that FILE should be the filename relative to the package root
 file does relative paths, they are assumed to be relative to the
 package root as well (and used without warning).
 
+Needs-Info requirements for using I<is_conffile>: L<Same as control|/control ([FILE])>
+
 =cut
 
-# sub is_conffile Needs-Info :control
 sub is_conffile {
     my ($self, $file) = @_;
     if (exists $self->{'conffiles'}) {
diff --git a/lib/Lintian/Collect/Changes.pm b/lib/Lintian/Collect/Changes.pm
index 5848288..deb1544 100644
--- a/lib/Lintian/Collect/Changes.pm
+++ b/lib/Lintian/Collect/Changes.pm
@@ -116,9 +116,10 @@ checksum.
 
 =back
 
+Needs-Info requirements for using I<files>: L<Lintian::Collect/field ([FIELD[, DEFAULT]])>
+
 =cut
 
-# sub files Needs-Info :fields
 sub files {
     my ($self) = @_;
 
diff --git a/lib/Lintian/Collect/Package.pm b/lib/Lintian/Collect/Package.pm
index df8022f..39f94a1 100644
--- a/lib/Lintian/Collect/Package.pm
+++ b/lib/Lintian/Collect/Package.pm
@@ -108,9 +108,10 @@ To get a list of entries in the package or the file meta data of the
 entries (as L<path objects|Lintian::Path>), see L</sorted_index> and
 L</index (FILE)>.
 
+Needs-Info requirements for using I<unpacked>: unpacked
+
 =cut
 
-# sub unpacked Needs-Info unpacked
 sub unpacked {
     my ($self, $file) = @_;
     return $self->_fetch_extracted_dir('unpacked', 'unpacked', $file);
@@ -123,6 +124,8 @@ Returns the output of file(1) for FILE (if it exists) or C<undef>.
 NB: The value may have been calibrated by Lintian.  A notorious example
 is gzip files, where file(1) can be unreliable at times (see #620289)
 
+Needs-Info requirements for using I<file_info>: file-info
+
 =cut
 
 sub file_info {
@@ -135,7 +138,6 @@ sub file_info {
     my %file_info;
     my $path = $self->lab_data_path ('file-info.gz');
     local $_;
-    # sub file_info Needs-Info file-info
     my $idx = open_gz ($path)
         or croak "cannot open $path: $!";
     while (<$idx>) {
@@ -168,9 +170,10 @@ To get a list of entries in the package, see L</sorted_index>.  To
 actually access the underlying file (e.g. the contents), use
 L</unpacked ([FILE])>.
 
+Needs-Info requirements for using I<index>: index
+
 =cut
 
-# sub index Needs-Info index
 sub index {
     my ($self, $file) = @_;
     return $self->_fetch_index_data('index', 'index', 'index-owner-id', $file);
@@ -187,9 +190,10 @@ The array will not contain the entry for the "root" of the package.
 NB: For source packages, please see the
 L<"index"-caveat|Lintian::Collect::Source/index (FILE)>.
 
+Needs-Info requirements for using I<sorted_index>: L<Same as index|/index (FILE)>
+
 =cut
 
-#  sub sorted_index Needs-Info :index
 sub sorted_index {
     my ($self) = @_;
     # index does all our work for us, so call it if sorted_index has
@@ -200,7 +204,7 @@ sub sorted_index {
 
 # Backing method for unpacked, debfiles and others; this is not a part of the
 # API.
-# sub _fetch_extracted_dir Needs-Info <>
+# sub _fetch_extracted_dir Needs-Info none
 sub _fetch_extracted_dir {
     my ($self, $field, $dirname, $file) = @_;
     my $dir = $self->{$field};
@@ -220,7 +224,7 @@ sub _fetch_extracted_dir {
 # Strip an extra layer quoting in index file names and optionally
 # remove an initial "./" if any.
 #
-# sub _dequote_name Needs-Info <>
+# sub _dequote_name Needs-Info none
 sub _dequote_name {
     my ($name, $slsd) = @_;
     $slsd = 1 unless defined $slsd; # Remove initial ./ by default
@@ -231,7 +235,7 @@ sub _dequote_name {
 }
 
 # Backing method for index and others; this is not a part of the API.
-# sub _fetch_index_data Needs-Info <>
+# sub _fetch_index_data Needs-Info none
 sub _fetch_index_data {
     my ($self, $field, $index, $indexown, $file) = @_;
     if (exists $self->{$index}) {
diff --git a/lib/Lintian/Collect/Source.pm b/lib/Lintian/Collect/Source.pm
index 4cc9c01..52bd034 100644
--- a/lib/Lintian/Collect/Source.pm
+++ b/lib/Lintian/Collect/Source.pm
@@ -94,9 +94,10 @@ object, or C<undef> if the changelog is a symlink or doesn't exist.  The
 debfiles collection script must have been run to create the changelog
 file, which this method expects to find in F<debfiles/changelog>.
 
+Needs-Info requirements for using I<changelog>: L<Same as debfiles|/debfiles ([FILE])>
+
 =cut
 
-# sub changelog Needs-Info :debfiles
 sub changelog {
     my ($self) = @_;
     return $self->{changelog} if exists $self->{changelog};
@@ -117,9 +118,10 @@ Returns the path to diffstat output run on the Debian packaging diff
 packages without a "diff.gz" component, this returns the path to an
 empty file (this may be a device like /dev/null).
 
+Needs-Info requirements for using I<diffstat>: diffstat
+
 =cut
 
-#  sub diffstat Needs-Info diffstat
 sub diffstat {
     my ($self) = @_;
     return $self->{diffstat} if exists $self->{diffstat};
@@ -143,9 +145,10 @@ ones).
 Note if the source format is missing, it is assumed to be an 1.0
 package.
 
+Needs-Info requirements for using I<native>: L<Same as field|Lintian::Collect/field ([FIELD[, DEFAULT]])>
+
 =cut
 
-# sub native Needs-Info :field
 sub native {
     my ($self) = @_;
     return $self->{native} if exists $self->{native};
@@ -176,9 +179,10 @@ sub native {
 Returns a list of the binary and udeb packages listed in the
 F<debian/control>.
 
+Needs-Info requirements for using I<binaries>: L<Same as binary_package_type|/binary_package_type (BINARY)>
+
 =cut
 
-# sub binaries Needs-Info :binary_package_type
 sub binaries {
     my ($self) = @_;
     # binary_package_type does all the work for us.
@@ -195,9 +199,9 @@ X-Package-Type) field.  If the field is omitted, the default value
 If the BINARY is not a binary listed in the source packages
 F<debian/control> file, this method return C<undef>.
 
-=cut
+Needs-Info requirements for using I<binary_package_type>: L<Same as binary_field|/binary_field (PACKAGE[, FIELD[, DEFAULT]])>
 
-# sub binary_package_type Needs-Info :binary_field
+=cut
 
 sub binary_package_type {
     my ($self, $binary) = @_;
@@ -238,9 +242,13 @@ F<debfiles/control> file available.
 NB: If a field from the "dsc" file itself is desired, please use
 L<field|Lintian::Collect/field> instead.
 
+Needs-Info requirements for using I<source_field>: L<Same as debfiles|/debfiles ([FILE])>
+
 =cut
 
-# sub source_field Needs-Info :_load_dctrl
+# NB: We don't say "same as _load_ctrl" in the above, because
+# _load_ctrl has no POD and would not appear in the generated
+# API-docs.
 sub source_field {
     my ($self, $field, $def) = @_;
     $self->_load_dctrl unless exists $self->{source_field};
@@ -260,9 +268,10 @@ NB: If sorted_index includes a debian packaging, it is was
 contained in upstream part of the source package (or the package is
 native).
 
+Needs-Info requirements for using I<orig_index>: src-orig-index
+
 =cut
 
-# sub orig_index Needs-Info src-orig-index
 sub orig_index {
     my ($self, $file) = @_;
     return $self->_fetch_index_data ('orig-index', 'src-orig-index', undef, $file);
@@ -281,9 +290,10 @@ NB: If sorted_orig_index includes a debian packaging, it is was
 contained in upstream part of the source package (or the package is
 native).
 
+Needs-Info requirements for using I<sorted_orig_index>: L<Same as orig_index|/orig_index ([FILE])>
+
 =cut
 
-# sub sorted_orig_index Needs-Info :orig_index
 sub sorted_orig_index {
     my ($self) = @_;
     # orig_index does all our work for us, so call it if
@@ -310,9 +320,13 @@ C<undef> regardless of FIELD and DEFAULT.
 The debfiles collection script must have been run to make the
 F<debfiles/control> file available.
 
+Needs-Info requirements for using I<binary_field>: L<Same as debfiles|/debfiles ([FILE])>
+
 =cut
 
-# sub binary_field Needs-Info :_load_dctrl
+# NB: We don't say "same as _load_ctrl" in the above, because
+# _load_ctrl has no POD and would not appear in the generated
+# API-docs.
 sub binary_field {
     my ($self, $package, $field, $def) = @_;
     $self->_load_dctrl unless exists $self->{binary_field};
@@ -410,9 +424,10 @@ object will be empty (always satisfied and implies nothing).
 Any substvars in F<debian/control> will be represented in the returned
 relation as packages named after the substvar.
 
+Needs-Info requirements for using I<binary_relation>: L<Same as binary_field|/binary_field (PACKAGE[, FIELD[, DEFAULT]])>
+
 =cut
 
-# sub binary_relation Needs-Info :binary_field
 sub binary_relation {
     my ($self, $package, $field) = @_;
     $field = lc $field;
@@ -460,9 +475,10 @@ The concatenation of Build-Conflicts and Build-Conflicts-Indep.
 If FIELD isn't present in the package, the returned Lintian::Relation
 object will be empty (always satisfied and implies nothing).
 
+Needs-Info requirements for using I<relation>: L<Same as field|Lintian::Collect/field ([FIELD[, DEFAULT]])>
+
 =cut
 
-# sub relation Needs-Info :field
 sub relation {
     my ($self, $field) = @_;
     $field = lc $field;
@@ -493,12 +509,10 @@ sub relation {
 The same as L</relation (FIELD)>, but ignores architecture
 restrictions in the FIELD field.
 
+Needs-Info requirements for using I<relation_noarch>: L<Same as field|Lintian::Collect/field ([FIELD[, DEFAULT]])>
+
 =cut
 
-# Similar to relation(), return a Lintian::Relation object for the given build
-# relationship field, but ignore architecture restrictions.  It supports the
-# same special field names.
-# sub relation_noarch Needs-Info :field
 sub relation_noarch {
     my ($self, $field) = @_;
     $field = lc $field;
@@ -537,12 +551,10 @@ entry.
 The caveats of L<unpacked|Lintian::Collect::Package/unpacked ([FILE])>
 also apply to this method.
 
+Needs-Info requirements for using I<debfiles>: debfiles
+
 =cut
 
-# Like unpacked except this only returns the contents of debian/ from a source
-# package.
-#
-# sub debfiles Needs-Info debfiles
 sub debfiles {
     my ($self, $file) = @_;
     return $self->_fetch_extracted_dir('debfiles', 'debfiles', $file);
@@ -588,13 +600,10 @@ question).
 Third, hardlinking information is lost and no attempt has been made
 to restore it.
 
+Needs-Info requirements for using I<index>: index
+
 =cut
 
-# Overridden method; please see Lintian::Collect::Package::index for
-# more information.
-#
-#
-# sub index Needs-Info index
 sub index {
     my ($self, $file) = @_;
     return $self->_fetch_index_data('index', 'index', undef, $file);
diff --git a/t/scripts/needs-info-missing.t b/t/scripts/needs-info-missing.t
index 90385ce..535cfed 100755
--- a/t/scripts/needs-info-missing.t
+++ b/t/scripts/needs-info-missing.t
@@ -49,16 +49,40 @@ for my $module (@MODULES) {
 	if (m/^\s*sub\s+(\w+)/) {
 	    $seen_subs{$1} = 1;
 	}
-	if (m/^\s*\#\s*sub\s+(\w+)\s+Needs-Info\s+(.*)$/) {
+	# We use "# sub X Needs-Info Y" for "internal" methods and
+	# the "Needs-Info requirements for using X: Y" for "public"
+	# methods.  The latter will appear in generated/processed
+	# documentations.
+	if (m/^\s*\#\s*sub\s+(\w+)\s+Needs-Info\s+(.*)$/ or
+		m/^\s*Needs-Info\s+requirements\s+for\s+using\s+I\<(\w+)\>\s*:\s*(.*)\s*$/) {
 	    my ($sub, $all_info) = ($1, $2);
 	    $seen_needsinfo{$sub} = 1;
+	    # Allow some L<> linking - it makes the generated
+	    # api-doc's a bit better than just reading the source.
+            $all_info =~ s,L\<[^\>]*/([A-Z0-9a-z_])+[^\>]*>,:$1,g;
+
 	    $all_info =~ s/\s//g;
 	    $all_info =~ s/,,/,/g;
+
+	    if ($all_info =~ m/[A-Z]\</) {
+		push @errors, "$sub has an (unknown/supported) POD formatting instruction\n";
+		next;
+	    }
 	    if (!$all_info) {
 		push @errors, "$sub has empty needs-info\n";
 		next;
 	    }
-	    $all_info =~ s/^<>$//;
+	    # While "none" technically is a valid name for a
+	    # collection, anyone reading:
+	    #
+	    #    Needs-Info requirements for using X: none"
+	    #
+	    #  (or "sub X Needs-Info none" for that matter)
+	    #
+	    # will almost certainly understand that as "there are no
+	    # dependencies".  Also "none" is more human-readable than
+	    # "<>" (which was used previously).
+	    $all_info = '' if $all_info eq 'none';
 	    if (exists($needs_info{$sub})) {
 		if ($all_info ne $needs_info{$sub}) {
 		    $needs_info{$sub} .= " or $all_info";

-- 
Debian package checker


Reply to: