Changeset 2350 for trunk/doc/misc/perlCodeConventions.tex

Timestamp:

Nov 12, 2004, 11:53:55 AM (22 years ago)

Author:

jhoblitt

Message:

add stand alone Pod format

File:

• trunk/doc/misc/perlCodeConventions.tex (modified) (5 diffs)

trunk/doc/misc/perlCodeConventions.tex

@@ -1 @@
-%%% $Id: perlCodeConventions.tex,v 1.6 2004-11-12 21:14:27 jhoblitt Exp $
+%%% $Id: perlCodeConventions.tex,v 1.7 2004-11-12 21:53:55 jhoblitt Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -28 +28 @@
 \begin{tabular}{|p{1in}|p{2.75in}|p{2.75in}|}
 \hline
+%%% References here.
 \textbf{\PS{} ID} & \textbf{Title} & \textbf{Author} \\
 430-004 &Pan-STARRS IPP C Code Standards    &Robert Lupton\\
-\hline
-%%% References here.
 \hline
 \end{tabular}
@@ -166 +165 @@
 # Copyright (C) 2004  Joshua Hoblitt
 #
-# $Id: perlCodeConventions.tex,v 1.6 2004-11-12 21:14:27 jhoblitt Exp $
+# $Id: perlCodeConventions.tex,v 1.7 2004-11-12 21:53:55 jhoblitt Exp $
 
 use 5.008005;   # optional
@@ -223 +222 @@
 # Copyright (C) 2004  Joshua Hoblitt
 #
-# $Id: perlCodeConventions.tex,v 1.6 2004-11-12 21:14:27 jhoblitt Exp $
+# $Id: perlCodeConventions.tex,v 1.7 2004-11-12 21:53:55 jhoblitt Exp $
 
 package Foo;
@@ -247 +246 @@
 
 \subsubsection{Perl Documentation}
+
+In most cases documentation should be included as in line Pod within a
+\code{.pl} file.  If a piece of stand alone documentation is required this is
+the general format that it should follow:
+
+\begin{verbatim}
+=pod
+
+=head1 NAME
+
+Foo - Does something with Baz.
+
+=head1 SYNOPSIS
+
+    use Foo;
+
+    ...
+
+=head1 DESCRIPTION
+
+More details about what this modules does with Baz.
+
+=head1 USAGE
+
+=head2 Import Parameters
+
+This module accepts no arguments to it's C<import> method and exports no
+I<symbols>.
+
+=head2 Methods
+
+=head3 Class Methods
+
+=over 4
+
+=item * methodOne
+
+details of methodOne
+
+=item * methodTwo
+
+details of methodTwo
+
+...
+
+=back
+
+=head1 SUPPORT
+
+Where to get help.
+
+=head1 AUTHOR
+
+Principle authors and contact info.
+
+=head1 COPYRIGHT
+
+Copyright (C) 2004  Robert Lupton.  All rights reserved.
+
+This program is free software; you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation; either version 2 of the License, or (at your option) any later
+version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with
+this program; if not, write to the Free Software Foundation, Inc., 59 Temple
+Place - Suite 330, Boston, MA  02111-1307, USA.
+
+The full text of the license can be found in the LICENSE file included with
+this module, or in the L<perlgpl> Pod as supplied with Perl 5.8.1 and later.
+
+=head1 SEE ALSO
+
+L<Bar::Baz>
+
+=cut
+\end{verbatim}
 
 %------------------------------------------------------------------------------