Generate documentation from Perl modules

Add rules to generate HTML from POD in Perl modules and scripts.
Generate docs from several EPICS/ Perl modules.

src/tools/EPICS/Getopts.pm

@@ -2,6 +2,76 @@ package EPICS::Getopts;
 require 5.000;
 require Exporter;
 
+=head1 NAME
+
+EPICS::Getopts - Process single-character command-line options
+
+=head1 SYNOPSIS
+
+    use EPICS::Getopts;
+
+    getopts('vo:I@') or die "Bad option\n";
+        # -v is a counted flag; -o takes an argument and
+        # sets $opt_o to its value; -I may be used more than
+        # once, the values are pushed onto @opt_I
+
+=head1 DESCRIPTION
+
+This version of getopts has been modified from the Perl original to add
+functionality that was needed by EPICS Perl applications. Some functionality of
+the original has also been removed. The main changes were:
+
+=over 2
+
+=item *
+
+Arguments without any modifiers are now counted, rather than storing a binary
+value in the C<$opt_x> variable. This means that multiple copies of the same
+option can be detected by the program.
+
+=item *
+
+A new B<C<@>> modifier is supported which collects the option arguments in an
+array C<@opt_x>. Multiple copies of this option can be given, which pushes each
+argument value onto the end of the array.
+
+=back
+
+
+=head1 FUNCTIONS
+
+=over 4
+
+=item B<C<getopts($argspec)>>
+
+The getopts() function processes single-character options. It takes one
+argument, a string containing all the options that should be recognized. For
+option letters in the string that are followed by a colon B<C<:>> it sets
+C<$opt_x> (where x is the option letter) to the value of that argument. For
+option letters followed by an at sign B<C<@>> it pushes each subsequent argument
+onto the array C<@opt_x> (where x is the option letter). For option letters
+without any qualifier it adds 1 to the value of C<$opt_x>. Options which take an
+argument don't care whether there is a space between the option and the
+argument.
+
+If unspecified switches are found on the command-line, the user will be warned
+that an unknown option was given. The getopts() function returns true unless an
+invalid option was found.
+
+Note that, if your code is running under the recommended C<use strict 'vars'>
+pragma, you will need to declare the necesary package variables with "our"
+before the call to getopts:
+
+    our($opt_v, $opt_o, @opt_I);
+
+To allow programs to process arguments that look like options but aren't, the
+function will stop processing options when it sees the argument B<C<-->>. The
+B<C<-->> will be removed from @ARGV.
+
+=back
+
+=cut
+
 @ISA = qw(Exporter);
 @EXPORT = qw(getopts);
 

src/tools/EPICS/Path.pm

@@ -7,17 +7,17 @@
 
 # $Revision-Id$
 
-use Carp;
-use Cwd qw(getcwd abs_path);
-use File::Spec;
+package EPICS::Path;
+require 5.000;
+require Exporter;
 
-=head1 EPICS::Path
+=head1 NAME
 
 EPICS::Path - Path-handling utilities for EPICS tools
 
 =head1 SYNOPSIS
 
-  use lib '@EPICS_BASE@/lib/perl';
+  use lib '/path/to/base/lib/perl';
   use EPICS::Path;
 
   my $dir = UnixPath('C:\Program Files\EPICS');
@@ -26,17 +26,29 @@ EPICS::Path - Path-handling utilities for EPICS tools
 
 =head1 DESCRIPTION
 
-C<EPICS::Path> provides functions for processing pathnames that are commonly
-needed by EPICS tools.  Windows is not the only culprit, some older automount
-daemons insert strange prefixes into absolute directory paths that we have to
-remove before storing the result for use later.
+This module provides functions for processing pathnames that are commonly needed
+by EPICS tools. Windows is not the only culprit, some older automount daemons
+insert strange prefixes into absolute directory paths that we have to remove
+before storing the result for use later.
 
+Note that these functions are only designed to work on operating systems that
+recognize a forward slash C</> as a directory separator; this does include
+Windows, but not pre-OS-X versions of MacOS which used a colon C<:> instead.
 
 =head1 FUNCTIONS
 
 =over 4
 
-=item UnixPath( I<PATH> )
+=cut
+
+use Carp;
+use Cwd qw(getcwd abs_path);
+use File::Spec;
+
+@ISA = qw(Exporter);
+@EXPORT = qw(UnixPath LocalPath AbsPath);
+
+=item B<C<UnixPath($path)>>
 
 C<UnixPath> should be used on any pathnames provided by external tools to
 convert them into a form that Perl understands.
@@ -57,7 +69,7 @@ sub UnixPath {
     return $newpath;
 }
 
-=item LocalPath( I<PATH> )
+=item B<C<LocalPath($path)>>
 
 C<LocalPath> should be used when generating pathnames for external tools or to
 put into a file.  It converts paths from the Unix form that Perl understands to
@@ -65,7 +77,7 @@ any necessary external representation, and also removes automounter prefixes to
 put the path into its canonical form.
 
 Before Leopard, the Mac OS X automounter inserted a verbose prefix, and in case
-anyone is still using SunOS it adds its own prefix as well.
+anyone is still using SunOS (pre-Solaris) it added its own prefix as well.
 
 =cut
 
@@ -81,19 +93,19 @@ sub LocalPath {
     return $newpath;
 }
 
-=item AbsPath( I<PATH> )
+=item B<C<AbsPath($path)>>
 
-=item AbsPath( I<PATH>, I<CWD> )
+=item B<C<AbsPath($path, $cwd)>>
 
-The C<abs_path()> function in Perl's C<Cwd> module doesn't like non-existent
+The C<abs_path()> function in Perl's F<Cwd> module doesn't like non-existent
 path components other than in the final position, but EPICS tools needs to be
 able to handle them in paths like F<$(TOP)/lib/$(T_A)> before the F<$(TOP)/lib>
 directory has been created.
 
-C<AbsPath> takes a path I<PATH> and optionally an absolute path to a directory
-that first is relative to; if the second argument is not provided the current
-working directory is used.  The result returned has been filtered through
-C<LocalPath()> to remove any automounter prefixes.
+C<AbsPath> takes a path C<$path> and optionally an absolute path to a directory
+that the first is relative to; if the second argument is not provided the
+current working directory is used instead. The result returned has also been
+filtered through C<LocalPath()> to remove any automounter prefixes.
 
 =cut
 
@@ -139,5 +151,4 @@ This software is distributed under the terms of the EPICS Open License.
 
 =cut
 
-
 1;

src/tools/EPICS/Readfile.pm

@@ -1,5 +1,5 @@
 #*************************************************************************
-# Copyright (c) 2010 UChicago Argonne LLC, as Operator of Argonne
+# Copyright (c) 2015 UChicago Argonne LLC, as Operator of Argonne
 #     National Laboratory.
 # EPICS BASE is distributed subject to a Software License Agreement found
 # in file LICENSE that is included with this distribution.
@@ -11,6 +11,28 @@ package EPICS::Readfile;
 require 5.000;
 require Exporter;
 
+=head1 NAME
+
+EPICS::Readfile - DBD and DB-file input for EPICS tools
+
+=head1 SYNOPSIS
+
+  use lib '/path/to/base/lib/perl';
+  use EPICS::macLib;
+  use EPICS::Readfile;
+
+  my $macros = EPICS::macLib->new('a=1', 'b=2');
+  my @path = qw(../dbd /opt/epics/base/dbd);
+  my $contents = Readfile('input.dbd', $macros, \@path);
+  printf "Read in %d files", scalar @inputfiles;
+
+=head1 DESCRIPTION
+
+This module provides a function for reading DBD and DB files that is commonly
+needed by EPICS tools.
+
+=cut
+
 use EPICS::macLib;
 
 @ISA = qw(Exporter);
@@ -69,6 +91,57 @@ sub unquote {
     return $s;
 }
 
+
+=head1 FUNCTIONS
+
+=over 4
+
+=item B<C<Readfile($file, $macros, \@path)>>
+
+This function reads an EPICS DBD or DB file into a string, substitutes any
+macros present, then parses the contents for any C<include>, C<addpath> and
+C<path> commands found therein and recursively executes those commands. The
+return value from the function is a string comprising the fully expanded
+contents of those files. Before executing them any commands will be replaced
+with specially formatted comments that allow the original command to be
+recovered during later parsing.
+
+I<Readfile> takes as arguments the input filename, an optional handle to a set
+of macro values from L<EPICS::macLib|macLib>, and a reference to an array
+containing the current search path.
+
+If macro expansion is not required, the second argument may be any boolean False
+value such as C<0> or C<()>. See L<EPICS::macLib|macLib> for more details about
+this argument.
+
+The path argument is a reference to an array of directory paths to be searched,
+in order. These paths may be used to locate the original input file and any
+include files that it references. The path array will be modified by any
+C<addpath> or C<path> commands found while parsing the input files.
+
+While processing input filenames (either the original argument or an include
+filename) if the filename does not contain any forward-slash C</> characters the
+path will be searched and the first file matching that name will be used. If the
+filename contains one or more forward-slash characters it must be either an
+absolute path or one that is relative to the current working directory; the
+search path is not used in this case.
+
+=back
+
+=head1 VARIABLES
+
+=over 4
+
+=item B<C<@inputfiles>>
+
+As new files are processed their names are added to this array which may be
+examimed after the I<Readfile> function returns, for example to calculate the
+complete set of dependencies for the input file.
+
+=back
+
+=cut
+
 sub Readfile {
     my ($file, $macros, $Rpath) = @_;
     print "Readfile($file)\n" if $debug;
@@ -98,4 +171,13 @@ sub Readfile {
     return join "\n", @output;
 }
 
+=head1 COPYRIGHT AND LICENSE
+
+Copyright (C) 2015 UChicago Argonne LLC, as Operator of Argonne National
+Laboratory.
+
+This software is distributed under the terms of the EPICS Open License.
+
+=cut
+
 1;