Add optional POD coverage testing

11 files changed, 233 insertions, 71 deletions

diff --git a/Changes b/Changes
index 42ea3f7..0cf63bf 100644
--- a/Changes
+++ b/Changes
@@ -1,5 +1,6 @@
 libnet 1.28  -- TODO
 
+  * Add optional POD coverage testing.
   * Add optional POD testing.
   * Add optional Perl::Critic testing.
   * Make code Perl::Critic clean.
diff --git a/MANIFEST b/MANIFEST
index c484723..8cca250 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -36,6 +36,7 @@ t/libnet_t.pl
 t/netrc.t
 t/nntp.t
 t/pod.t
+t/pod_coverage.t
 t/require.t
 t/smtp.t
 t/smtp_ssl.t
diff --git a/Makefile.PL b/Makefile.PL
index 3921a4a..b41a3c9 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -137,6 +137,17 @@ MAIN: {
                             }
                         }
                     }
+                },
+
+                podcoveragetest => {
+                    description => 'POD coverage testing',
+                    prereqs => {
+                        test => {
+                            requires => {
+                                'Test::Pod::Coverage' => '0.08'
+                            }
+                        }
+                    }
                 }
             }
         },
@@ -171,6 +182,7 @@ MAIN: {
             'Socket'         => '1.3',
             'Symbol'         => '0',
             'Time::Local'    => '0',
+            'constant'       => '0',
             'strict'         => '0',
             'vars'           => '0'
         },
diff --git a/lib/Net/Cmd.pm b/lib/Net/Cmd.pm
index efa8c07..9bf9f4f 100644
--- a/lib/Net/Cmd.pm
+++ b/lib/Net/Cmd.pm
@@ -45,13 +45,12 @@ our $VERSION = "2.31";
 our @ISA     = qw(Exporter);
 our @EXPORT  = qw(CMD_INFO CMD_OK CMD_MORE CMD_REJECT CMD_ERROR CMD_PENDING);
 
-
-sub CMD_INFO    {1}
-sub CMD_OK      {2}
-sub CMD_MORE    {3}
-sub CMD_REJECT  {4}
-sub CMD_ERROR   {5}
-sub CMD_PENDING {0}
+use constant CMD_INFO    => 1;
+use constant CMD_OK      => 2;
+use constant CMD_MORE    => 3;
+use constant CMD_REJECT  => 4;
+use constant CMD_ERROR   => 5;
+use constant CMD_PENDING => 0;
 
 my %debug = ();
 
diff --git a/lib/Net/Config.pm b/lib/Net/Config.pm
index 524b4bc..18da9d1 100644
--- a/lib/Net/Config.pm
+++ b/lib/Net/Config.pm
@@ -163,7 +163,7 @@ C<Net::LocalCfg> so you can override these methods if you want.
 
 =over 4
 
-=item requires_firewall HOST
+=item requires_firewall ( HOST )
 
 Attempts to determine if a given host is outside your firewall. Possible
 return values are.
diff --git a/lib/Net/FTP.pm b/lib/Net/FTP.pm
index 2939d1d..302c81a 100644
--- a/lib/Net/FTP.pm
+++ b/lib/Net/FTP.pm
@@ -27,16 +27,11 @@ use Time::Local;
 our $VERSION = '2.80';
 our @ISA     = qw(Exporter Net::Cmd IO::Socket::INET);
 
-# Someday I will "use constant", when I am not bothered to much about
-# compatibility with older releases of perl
+use constant TELNET_IAC => 255;
+use constant TELNET_IP  => 244;
+use constant TELNET_DM  => 242;
 
-our($TELNET_IAC, $TELNET_IP, $TELNET_DM) = (255, 244, 242);
-
-BEGIN {
-  # make a constant so code is fast'ish
-  my $is_os390 = $^O eq 'os390';
-  *trEBCDIC = sub () {$is_os390}
-}
+use constant EBCDIC => $^O eq 'os390';
 
 sub new {
   my $pkg = shift;
@@ -427,9 +422,9 @@ sub alloc {
 sub abort {
   my $ftp = shift;
 
-  send($ftp, pack("CCC", $TELNET_IAC, $TELNET_IP, $TELNET_IAC), MSG_OOB);
+  send($ftp, pack("CCC", TELNET_IAC, TELNET_IP, TELNET_IAC), MSG_OOB);
 
-  $ftp->command(pack("C", $TELNET_DM) . "ABOR");
+  $ftp->command(pack("C", TELNET_DM) . "ABOR");
 
   ${*$ftp}{'net_ftp_dataconn'}->close()
     if defined ${*$ftp}{'net_ftp_dataconn'};
@@ -495,7 +490,7 @@ sub get {
   while (1) {
     last unless $len = $data->read($buf, $blksize);
 
-    if (trEBCDIC && $ftp->type ne 'I') {
+    if (EBCDIC && $ftp->type ne 'I') {
       $buf = $ftp->toebcdic($buf);
       $len = length($buf);
     }
@@ -753,7 +748,7 @@ sub _store_cmd {
   while (1) {
     last unless $len = read($loc, $buf = "", $blksize);
 
-    if (trEBCDIC && $ftp->type ne 'I') {
+    if (EBCDIC && $ftp->type ne 'I') {
       $buf = $ftp->toascii($buf);
       $len = length($buf);
     }
@@ -988,7 +983,7 @@ sub _list_cmd {
 
   $data->close();
 
-  if (trEBCDIC) {
+  if (EBCDIC) {
     for (@$list) { $_ = $ftp->toebcdic($_) }
   }
 
@@ -1327,7 +1322,9 @@ EBCDIC format.  Binary (also known as image) format sends the data as
 a contiguous bit stream.  Byte format transfers the data as bytes, the
 values of which remain the same regardless of differences in byte size
 between the two machines (in theory - in practice you should only use
-this if you really know what you're doing).
+this if you really know what you're doing).  This class does not support
+the EBCDIC or byte formats, and will default to binary instead if they
+are attempted.
 
 =head1 CONSTRUCTOR
 
@@ -1349,7 +1346,6 @@ the C<PeerAddr> option in L<IO::Socket::INET>, or a reference to
 an array with hosts to try in turn. The L</host> method will return the value
 which was used to connect to the host.
 
-
 B<Firewall> - The name of a machine which acts as an FTP firewall. This can be
 overridden by an environment variable C<FTP_FIREWALL>. If specified, and the
 given host cannot be directly connected to, then the
@@ -1424,6 +1420,15 @@ will be used for password.
 If the connection is via a firewall then the C<authorize> method will
 be called with no arguments.
 
+=item host ()
+
+Returns the value used by the constructor, and passed to IO::Socket::INET,
+to connect to the host.
+
+=item account( ACCT )
+
+Set a string identifying the user's account.
+
 =item authorize ( [AUTH [, RESP]])
 
 This is a protocol used by some firewall ftp proxies. It is used
@@ -1436,17 +1441,21 @@ Send a SITE command to the remote server and wait for a response.
 
 Returns most significant digit of the response code.
 
-=item ascii
+=item ascii ()
 
 Transfer file in ASCII. CRLF translation will be done if required
 
-=item binary
+=item binary ()
 
 Transfer file in binary mode. No transformation will be done.
 
 B<Hint>: If both server and client machines use the same line ending for
 text files, then it will be faster to transfer all files in binary mode.
 
+=item type ( [ TYPE ] )
+
+Set or get if files will be transferred in ASCII or binary mode.
+
 =item rename ( OLDNAME, NEWNAME )
 
 Rename a file on the remote FTP server from C<OLDNAME> to C<NEWNAME>. This
@@ -1725,44 +1734,8 @@ data connections. Misuse of this method can hang the connection.
 =head1 THE dataconn CLASS
 
 Some of the methods defined in C<Net::FTP> return an object which will
-be derived from this class.The dataconn class itself is derived from
-the C<IO::Socket::INET> class, so any normal IO operations can be performed.
-However the following methods are defined in the dataconn class and IO should
-be performed using these.
-
-=over 4
-
-=item read ( BUFFER, SIZE [, TIMEOUT ] )
-
-Read C<SIZE> bytes of data from the server and place it into C<BUFFER>, also
-performing any <CRLF> translation necessary. C<TIMEOUT> is optional, if not
-given, the timeout value from the command connection will be used.
-
-Returns the number of bytes read before any <CRLF> translation.
-
-=item write ( BUFFER, SIZE [, TIMEOUT ] )
-
-Write C<SIZE> bytes of data from C<BUFFER> to the server, also
-performing any <CRLF> translation necessary. C<TIMEOUT> is optional, if not
-given, the timeout value from the command connection will be used.
-
-Returns the number of bytes written before any <CRLF> translation.
-
-=item bytes_read ()
-
-Returns the number of bytes read so far.
-
-=item abort ()
-
-Abort the current data transfer.
-
-=item close ()
-
-Close the data connection and get a response from the FTP server. Returns
-I<true> if the connection was closed successfully and the first digit of
-the response from the server was a '2'.
-
-=back
+be derived from the C<Net::FTP::dataconn> class. See L<Net::FTP::dataconn> for
+more details.
 
 =head1 UNIMPLEMENTED
 
diff --git a/lib/Net/FTP/dataconn.pm b/lib/Net/FTP/dataconn.pm
index 76ea14a..3719a27 100644
--- a/lib/Net/FTP/dataconn.pm
+++ b/lib/Net/FTP/dataconn.pm
@@ -128,3 +128,53 @@ sub bytes_read {
 }
 
 1;
+
+__END__
+
+=head1 NAME
+
+Net::FTP::dataconn - FTP Client data connection class
+
+=head1 DESCRIPTION
+
+Some of the methods defined in C<Net::FTP> return an object which will
+be derived from this class. The dataconn class itself is derived from
+the C<IO::Socket::INET> class, so any normal IO operations can be performed.
+However the following methods are defined in the dataconn class and IO should
+be performed using these.
+
+=over 4
+
+=item read ( BUFFER, SIZE [, TIMEOUT ] )
+
+Read C<SIZE> bytes of data from the server and place it into C<BUFFER>, also
+performing any <CRLF> translation necessary. C<TIMEOUT> is optional, if not
+given, the timeout value from the command connection will be used.
+
+Returns the number of bytes read before any <CRLF> translation.
+
+=item write ( BUFFER, SIZE [, TIMEOUT ] )
+
+Write C<SIZE> bytes of data from C<BUFFER> to the server, also
+performing any <CRLF> translation necessary. C<TIMEOUT> is optional, if not
+given, the timeout value from the command connection will be used.
+
+Returns the number of bytes written before any <CRLF> translation.
+
+=item bytes_read ()
+
+Returns the number of bytes read so far.
+
+=item abort ()
+
+Abort the current data transfer.
+
+=item close ()
+
+Close the data connection and get a response from the FTP server. Returns
+I<true> if the connection was closed successfully and the first digit of
+the response from the server was a '2'.
+
+=back
+
+=cut
diff --git a/lib/Net/NNTP.pm b/lib/Net/NNTP.pm
index 9b729ed..790b6db 100644
--- a/lib/Net/NNTP.pm
+++ b/lib/Net/NNTP.pm
@@ -773,6 +773,11 @@ documented here.
 
 =over 4
 
+=item host ()
+
+Returns the value used by the constructor, and passed to IO::Socket::INET,
+to connect to the host.
+
 =item article ( [ MSGID|MSGNUM ], [FH] )
 
 Retrieve the header, a blank line, then the body (text) of the
@@ -838,6 +843,11 @@ In an array context the return value is a list containing, the number
 of articles in the group, the number of the first article, the number
 of the last article and the group name.
 
+=item help ( )
+
+Request help text (a short summary of commands that are understood by this
+implementation) from the server. Returns the text or undef upon failure.
+
 =item ihave ( MSGID [, MESSAGE ])
 
 The C<ihave> command informs the server that the client has an article
@@ -871,11 +881,17 @@ that it will allow posting.
 
 =item authinfo ( USER, PASS )
 
-Authenticates to the server (using AUTHINFO USER / AUTHINFO PASS)
-using the supplied username and password.  Please note that the
-password is sent in clear text to the server.  This command should not
-be used with valuable passwords unless the connection to the server is
-somehow protected.
+Authenticates to the server (using the original AUTHINFO USER / AUTHINFO PASS
+form, defined in RFC2980) using the supplied username and password.  Please
+note that the password is sent in clear text to the server.  This command
+should not be used with valuable passwords unless the connection to the server
+is somehow protected.
+
+=item authinfo_simple ( USER, PASS )
+
+Authenticates to the server (using the proposed NNTP V2 AUTHINFO SIMPLE form,
+defined and deprecated in RFC2980) using the supplied username and password.
+As with L</authinfo> the password is sent in clear text.
 
 =item list ()
 
@@ -961,6 +977,13 @@ each value contains the description text for the group.
 Returns a reference to a hash where the keys are all the possible
 distribution names and the values are the distribution descriptions.
 
+=item distribution_patterns ()
+
+Returns a reference to an array where each element, itself an array
+reference, consists of the three fields of a line of the distrib.pats list
+maintained by some NNTP servers, namely: a weight, a wildmat and a value
+which the client may use to construct a Distribution header.
+
 =item subscriptions ()
 
 Returns a reference to a list which contains a list of groups which
@@ -1014,7 +1037,7 @@ message.
 The result is the same as C<xhdr> except the is will be restricted to
 headers where the text of the header matches C<PATTERN>
 
-=item xrover
+=item xrover ()
 
 The XROVER command returns reference information for the article(s)
 specified.
@@ -1027,7 +1050,7 @@ values are the References: lines from the articles
 Returns a reference to a list of all the active messages in C<GROUP>, or
 the current group if C<GROUP> is not specified.
 
-=item reader
+=item reader ()
 
 Tell the server that you are a reader and not another server.
 
diff --git a/lib/Net/POP3.pm b/lib/Net/POP3.pm
index 85c6457..772bf76 100644
--- a/lib/Net/POP3.pm
+++ b/lib/Net/POP3.pm
@@ -680,6 +680,11 @@ documented here.
 
 =over 4
 
+=item host ()
+
+Returns the value used by the constructor, and passed to IO::Socket::INET,
+to connect to the host.
+
 =item auth ( USERNAME, PASSWORD )
 
 Attempt SASL authentication.
@@ -800,6 +805,14 @@ status of all messages to not be deleted.
 Quit and close the connection to the remote POP3 server. Any messages marked
 as deleted will be deleted from the remote mailbox.
 
+=item can_inet6 ()
+
+Returns whether we can use IPv6.
+
+=item can_ssl ()
+
+Returns whether we can use SSL.
+
 =back
 
 =head1 NOTES
diff --git a/lib/Net/SMTP.pm b/lib/Net/SMTP.pm
index 9e537e5..4e0c387 100644
--- a/lib/Net/SMTP.pm
+++ b/lib/Net/SMTP.pm
@@ -936,6 +936,13 @@ If C<DATA> is not specified then the result will indicate that the server
 wishes the data to be sent. The data must then be sent using the C<datasend>
 and C<dataend> methods described in L<Net::Cmd>.
 
+=item bdat ( DATA )
+
+=item bdatlast ( DATA )
+
+Use the alternate DATA command "BDAT" of the data chunking service extension
+defined in RFC1830 for efficiently sending large MIME messages.
+
 =item expand ( ADDRESS )
 
 Request the server to expand the given address Returns an array
@@ -956,6 +963,14 @@ Request help text from the server. Returns the text or undef upon failure
 
 Send the QUIT command to the remote SMTP server and close the socket connection.
 
+=item can_inet6 ()
+
+Returns whether we can use IPv6.
+
+=item can_ssl ()
+
+Returns whether we can use SSL.
+
 =back
 
 =head1 ADDRESSES
diff --git a/t/pod_coverage.t b/t/pod_coverage.t
new file mode 100644
index 0000000..d72778c
--- /dev/null
+++ b/t/pod_coverage.t
@@ -0,0 +1,75 @@
+#!perl

+#===============================================================================

+#

+# t/pod_coverage.t

+#

+# DESCRIPTION

+#   Test script to check POD coverage.

+#

+# COPYRIGHT

+#   Copyright (C) 2014 Steve Hay.  All rights reserved.

+#

+# LICENCE

+#   You may distribute under the terms of either the GNU General Public License

+#   or the Artistic License, as specified in the LICENCE file.

+#

+#===============================================================================

+

+use 5.008001;

+

+use strict;

+use warnings;

+

+use Test::More;

+

+#===============================================================================

+# MAIN PROGRAM

+#===============================================================================

+

+MAIN: {

+    my $ok = eval {

+        require Test::Pod::Coverage;

+        Test::Pod::Coverage->import();

+        1;

+    };

+

+    if (not $ok) {

+        plan skip_all => 'Test::Pod::Coverage required to test POD coverage';

+    }

+    elsif ($Test::Pod::Coverage::VERSION < 0.08) {

+        plan skip_all => 'Test::Pod::Coverage 0.08 or higher required to test POD coverage';

+    }

+    else {

+        plan tests => 12;

+        my $params = { coverage_class => qw(Pod::Coverage::CountParents) };

+        pod_coverage_ok('Net::Cmd', {

+            %$params,

+            also_private => [qw(is_utf8 toascii toebcdic set_status)]

+        });

+        pod_coverage_ok('Net::Config', {

+            %$params,

+            also_private => [qw(is_external)]

+        });

+        pod_coverage_ok('Net::Domain', $params);

+        pod_coverage_ok('Net::FTP',  {

+            %$params,

+            also_private => [qw(authorise lsl ebcdic byte cmd)]

+        });

+        pod_coverage_ok('Net::Netrc', $params);

+        pod_coverage_ok('Net::NNTP', $params);

+        pod_coverage_ok('Net::POP3', $params);

+        pod_coverage_ok('Net::SMTP', {

+            %$params,

+            also_private => [qw(datafh supports)]

+        });

+        pod_coverage_ok('Net::Time', $params);

+        pod_coverage_ok('Net::FTP::A', $params);

+        pod_coverage_ok('Net::FTP::dataconn', {

+            %$params,

+            also_private => [qw(can_read can_write cmd reading)]

+        });

+        pod_coverage_ok('Net::FTP::I', $params);

+    }

+}

+

+#===============================================================================