Merge pull request #1277 from tgreenx/improve-pod

Improve POD documentation in Test modules (and a few others)

docs/Implementing_Tests.pod

@@ -15,7 +15,7 @@ to the framework.
 
 =item Make as few assumptions as possible.
 
-When the entry method in a test module is called, it can rely on only a handful of things about the testing process so far:
+When the entry method in a test module is called, it can only rely on a handful of things about the testing process so far:
 
 =over
 
@@ -35,8 +35,8 @@ The zone object it's given has nameservers.
 
 =item Favor code clarity over performance.
 
-Strive to make the test code as easily understood as possible. Ideally, it should be possible for a person with only a basic understanding of Perl to
-read the code and verify that it correctly implements the corresponding test specification. 
+Strive to make the test code as easily understandable as possible. Ideally, it should be possible for a person with only a basic understanding of Perl to
+read the code and verify that it correctly implements the corresponding Test Case specifications.
 
 =back
 
@@ -58,18 +58,14 @@ message, but otherwise not used.
 =item C<metadata()>
 
 This method should return a reference to a hash. The keys of this hash should be the names of the individual test methods in the module, and the
-values for each key should be a reference to an array listing all the possible messages that test method can emit. 
+values for each key should be a reference to an array listing all the possible messages that test methods can emit.
 
 =back
 
 =head2 Test-running method(s)
 
-The framework expects to be able to run all tests in a module by calling a class method C<all()> with a L<Zonemaster::Engine::Zone> object as the argument.
-The return value from this method is expected to be a list of L<Zonemaster::Engine::Logger::Entry> objects describing the results of the tests run. The
-example test module has one possible implementation of this.
-
-In the case where one test module wants to use a test in another, the top-level L<Zonemaster::Engine> module has a method C<test_method()> to request that.
-This method will call the other test, if it is available and the current policy allows its execution. It's up to the caller to know what arguments
-the other test needs, and what it returns.
+The framework expects to be able to run all tests in a module by calling a class method L<all()|Zonemaster::Engine::Test/all()> with a
+L<Zonemaster::Engine::Zone> object as the argument.
+The return value from this method is expected to be a list of L<Zonemaster::Engine::Logger::Entry> objects describing the results of the tests run.
 
 =cut

docs/Translation.pod

@@ -13,8 +13,8 @@ executed from that directory.
 
 =head2 For translators
 
-Instructions for translators can be found in
-L<https://github.com/zonemaster/zonemaster/blob/develop/docs/internal-documentation/maintenance/Instructions-for-translators.md>
+Instructions for translators can be found at
+L<https://github.com/zonemaster/zonemaster/blob/develop/docs/internal/maintenance/Instructions-for-translators.md>
 
 =head2 For developers of Zonemaster test modules
 
@@ -45,10 +45,6 @@ The format strings themselves, the comments and the line numbers of the __x
 calls are used by the gettext tooling when updating the PO files with new
 message ids and old message strings.
 
-Every time you add, remove or modify a tag or its message id, re-run
-C<make update-po> as descibed in the next section.
-Make sure the message tag comments are properly added and up to date.
-
 =head2 For Zonemaster package maintainers
 
 In order to make a new translation usable, it must be compiled to C<mo> format

lib/Zonemaster/Engine.pm

@@ -263,7 +263,7 @@ Runs all available tests for the zone with the given name in the specified modul
 =item test_method($module, $method, @arguments)
 
 Run one particular test method in one particular module. The requested module must be in the list of active loaded modules (that is, not the Basic
-module and not a module disabled by the current policy), and the method must be listed in the metadata the module exports. If those requirements
+module and not a module disabled by the current profile), and the method must be listed in the metadata the module exports. If those requirements
 are fulfilled, the method will be called with the provided arguments.
 
 =item zone($name)

lib/Zonemaster/Engine/Constants.pm

@@ -16,6 +16,50 @@ use File::ShareDir qw[dist_dir dist_file];
 
 use Readonly;
 
+=head1 NAME
+
+Zonemaster::Engine::Constants - module holding constants used in Test modules
+
+=head1 SYNOPSIS
+
+   use Zonemaster::Engine::Constants ':all';
+
+=head1 EXPORTED GROUPS
+
+=over
+
+=item all
+
+All exportable names.
+
+=item algo
+
+DNSSEC algorithms.
+
+=item name
+
+Label and name lengths.
+
+=item ip
+
+IP version constants.
+
+=item soa
+
+SOA values limits.
+
+=item misc
+
+Other, uncategorized export names, e.g. UDP payload limit and minimum number of name servers per zone.
+
+=item addresses
+
+Address classes for IPv4 and IPv6.
+
+=back
+
+=cut
+
 our @EXPORT_OK = qw[
   $ALGO_STATUS_DEPRECATED
   $ALGO_STATUS_PRIVATE
@@ -62,6 +106,70 @@ our %EXPORT_TAGS = (
     addresses => [qw(@IPV4_SPECIAL_ADDRESSES @IPV6_SPECIAL_ADDRESSES)],
 );
 
+=head1 EXPORTED NAMES
+
+=over
+
+=item * C<$ALGO_STATUS_DEPRECATED>
+
+=item * C<$ALGO_STATUS_PRIVATE>
+
+=item * C<$ALGO_STATUS_RESERVED>
+
+=item * C<$ALGO_STATUS_UNASSIGNED>
+
+=item * C<$ALGO_STATUS_OTHER>
+
+=item * C<$ALGO_STATUS_NOT_RECOMMENDED>
+
+=item * C<$ALGO_STATUS_NOT_ZONE_SIGN>
+
+=item * C<$DURATION_5_MINUTES_IN_SECONDS>
+
+=item * C<$DURATION_1_HOUR_IN_SECONDS>
+
+=item * C<$DURATION_4_HOURS_IN_SECONDS>
+
+=item * C<$DURATION_12_HOURS_IN_SECONDS>
+
+=item * C<$DURATION_1_DAY_IN_SECONDS>
+
+=item * C<$DURATION_1_WEEK_IN_SECONDS>
+
+=item * C<$DURATION_180_DAYS_IN_SECONDS>
+
+=item * C<$FQDN_MAX_LENGTH>
+
+=item * C<$LABEL_MAX_LENGTH>
+
+=item * C<$IP_VERSION_4>
+
+=item * C<$IP_VERSION_6>
+
+=item * C<$SERIAL_BITS>
+
+An integer, used to define the size of the serial number space, as defined in RFC1982, section 2.
+
+=item * C<$SERIAL_MAX_VARIATION>
+
+=item * C<$MINIMUM_NUMBER_OF_NAMESERVERS>
+
+=item * C<$UDP_PAYLOAD_LIMIT>
+
+=item * C<$UDP_EDNS_QUERY_DEFAULT>
+
+An integer, used to define the EDNS0 UDP packet size in EDNS queries.
+
+=item * C<$UDP_COMMON_EDNS_LIMIT>
+
+=item * C<@IPV4_SPECIAL_ADDRESSES>
+
+=item * C<@IPV6_SPECIAL_ADDRESSES>
+
+=back
+
+=cut
+
 Readonly our $ALGO_STATUS_DEPRECATED      => 1;
 Readonly our $ALGO_STATUS_PRIVATE         => 4;
 Readonly our $ALGO_STATUS_RESERVED        => 2;
@@ -102,6 +210,24 @@ Readonly::Array our @IPV4_SPECIAL_ADDRESSES => _extract_iana_ip_blocks($IP_VERSI
 
 Readonly::Array our @IPV6_SPECIAL_ADDRESSES => _extract_iana_ip_blocks($IP_VERSION_6);
 
+=head1 METHODS
+
+=over
+
+=item _extract_iana_ip_blocks()
+
+    my @array = _extract_iana_ip_blocks( $ip_version );
+
+Internal method that is used to extract IP blocks details from IANA files for a given IP version (i.e. 4 or 6).
+
+Takes an integer (IP version).
+
+Returns a list of hashes - the keys of which are C<ip> (L<Net::IP::XS> object), C<name> (string) and C<reference> (string).
+
+=back
+
+=cut
+
 sub _extract_iana_ip_blocks {
     my $ip_version = shift;
     my @list = ();
@@ -141,165 +267,3 @@ sub _extract_iana_ip_blocks {
 } ## end sub _extract_iana_ip_blocks
 
 1;
-
-=head1 NAME
-
-Zonemaster::Engine::Constants - module holding constants used in test modules
-
-=head1 SYNOPSIS
-
-   use Zonemaster::Engine::Constants ':all';
-
-=head1 EXPORTED GROUPS
-
-=over
-
-=item all
-
-All exportable names.
-
-=item algo
-
-DNSSEC algorithms.
-
-=item name
-
-Label and name lengths.
-
-=item ip
-
-IP version constants.
-
-=item soa
-
-SOA value limits.
-
-=item misc
-
-UDP payload limit and minimum number of nameservers per zone.
-
-=item addresses
-
-Address classes for IPv4 and IPv6.
-
-=item extract_iana_ip_blocks($ip_version)
-
-Will extract IPs details from IANA files.
-
-=back
-
-=head1 EXPORTED NAMES
-
-=over
-
-=item *
-
-C<$ALGO_STATUS_DEPRECATED>
-
-=item *
-
-C<$ALGO_STATUS_PRIVATE>
-
-=item *
-
-C<$ALGO_STATUS_RESERVED>
-
-=item *
-
-C<$ALGO_STATUS_UNASSIGNED>
-
-=item *
-
-C<$ALGO_STATUS_OTHER>
-
-=item *
-
-C<$ALGO_STATUS_NOT_RECOMMENDED>
-
-=item *
-
-C<$ALGO_STATUS_NOT_ZONE_SIGN>
-
-=item *
-
-C<$DURATION_5_MINUTES_IN_SECONDS>
-
-=item *
-
-C<$DURATION_1_HOUR_IN_SECONDS>
-
-=item *
-
-C<$DURATION_4_HOURS_IN_SECONDS>
-
-=item *
-
-C<$DURATION_12_HOURS_IN_SECONDS>
-
-=item *
-
-C<$DURATION_1_DAY_IN_SECONDS>
-
-=item *
-
-C<$DURATION_1_WEEK_IN_SECONDS>
-
-=item *
-
-C<$DURATION_180_DAYS_IN_SECONDS>
-
-=item *
-
-C<$FQDN_MAX_LENGTH>
-
-=item *
-
-C<$LABEL_MAX_LENGTH>
-
-=item *
-
-C<$IP_VERSION_4>
-
-=item *
-
-C<$IP_VERSION_6>
-
-=item *
-
-C<$SERIAL_BITS>
-
-An integer, used to define the size of the serial number space, as defined in RFC1982, section 2.
-
-=item *
-
-C<$SERIAL_MAX_VARIATION>
-
-=item *
-
-C<$MINIMUM_NUMBER_OF_NAMESERVERS>
-
-=item *
-
-C<$UDP_PAYLOAD_LIMIT>
-
-=item *
-
-C<$UDP_EDNS_QUERY_DEFAULT>
-
-An integer, used to define the EDNS0 UDP packet size in EDNS queries.
-
-=item *
-
-C<UDP_COMMON_EDNS_LIMIT>
-
-=item *
-
-C<@IPV4_SPECIAL_ADDRESSES>
-
-=item *
-
-C<@IPV6_SPECIAL_ADDRESSES>
-
-=back
-
-=cut