Documentation render change, add POD::Checker testing the syntax

Author: mtmail

Changes

@@ -11,6 +11,7 @@ unreleased
         - accept HTTP::Response subclasses (content/is_success branches stayed in sync)
         documentation:
         - document http=>1 and ua=>$ua parameters of new()
+        - restructure geocode() Supported/Not Supported sections into proper =head3/=over blocks
         - We documented user-agent string as "Geo::Coder::OpenCage/$VERSION" but in code it
            used space as delimiter. It's also set when another UA is supplied in new() as
            documented.
@@ -22,6 +23,7 @@ unreleased
         - new tests for JSON decoding and API-key masking
         - new test for HTTP::Response subclasses
         - new tests for reverse geocoding calling without required parameters (lat,lng)
+        - test the Perl documentation (POD) syntax
         release tooling:
         - abort (die) instead of warn on untracked files
         - .gitignore: drop dead entries, ignore dotted dirs except .github

lib/Geo/Coder/OpenCage.pm

@@ -258,16 +258,16 @@ L<OpenCage geocoding API response codes|https://opencagedata.com/api#codes>
   }
 
 
-=over 
-
-=item Supported Parameters
+=head3 Supported Parameters
 
 The OpenCage Geocoder has a few optional parameters.
 
 Please see L<the OpenCage geocoder documentation|https://opencagedata.com/api>. Most of L<the various optional parameters|https://opencagedata.com/api#forward-opt> are supported.
 
 The most commonly useful parameters are:
 
+=over
+
 =item language
 
 An IETF format language code (such as es for Spanish or pt-BR for Brazilian
@@ -285,6 +285,8 @@ the supplied country.
 
 The countrycode is a comma separated list of 2 character code as defined by the ISO 3166-1 Alpha 2 standard.
 
+=back
+
 As a full example:
 
     my $response = $Geocoder->geocode(
@@ -293,18 +295,19 @@ As a full example:
         countrycode => "ru",
     );
 
+=head3 Not Supported
 
-=item Not Supported
+=over
 
 =item jsonp
 
 This module always parses the response as a Perl data structure, so the jsonp
 option is never used.
 
-All other API parameters are passed through directly
-
 =back
 
+All other API parameters are passed through directly.
+
 =head2 reverse_geocode
 
 Takes two named parameters 'lat' and 'lng' and returns a result hashref.

t/12-pod.t

@@ -0,0 +1,24 @@
+use strict;
+use warnings;
+use Test::More;
+use Pod::Checker;
+
+use lib './lib'; # actually use the module, not other versions installed
+
+my @files = ('lib/Geo/Coder/OpenCage.pm');
+
+for my $file (@files) {
+    # Capture Pod::Checker's diagnostic output so test output stays clean,
+    # and we can diag() it on failure.
+    my $output = '';
+    open my $fh, '>', \$output or die "open scalar: $!";
+
+    my $checker = Pod::Checker->new();
+    $checker->parse_from_file($file, $fh);
+    close $fh;
+
+    is($checker->num_errors, 0, "$file: POD has no errors")
+        or diag($output);
+}
+
+done_testing();