📄 ch26_05.htm
字号:
<html><head><title>Documenting Your Perl Programs (Programming Perl)</title><!-- STYLESHEET --><link rel="stylesheet" type="text/css" href="../style/style1.css"><!-- METADATA --><!--Dublin Core Metadata--><meta name="DC.Creator" content=""><meta name="DC.Date" content=""><meta name="DC.Format" content="text/xml" scheme="MIME"><meta name="DC.Generator" content="XSLT stylesheet, xt by James Clark"><meta name="DC.Identifier" content=""><meta name="DC.Language" content="en-US"><meta name="DC.Publisher" content="O'Reilly & Associates, Inc."><meta name="DC.Source" content="" scheme="ISBN"><meta name="DC.Subject.Keyword" content=""><meta name="DC.Title" content="Documenting Your Perl Programs"><meta name="DC.Type" content="Text.Monograph"></head><body><!-- START OF BODY --><!-- TOP BANNER --><img src="gifs/smbanner.gif" usemap="#banner-map" border="0" alt="Book Home"><map name="banner-map"><AREA SHAPE="RECT" COORDS="0,0,466,71" HREF="index.htm" ALT="Programming Perl"><AREA SHAPE="RECT" COORDS="467,0,514,18" HREF="jobjects/fsearch.htm" ALT="Search this book"></map><!-- TOP NAV BAR --><div class="navbar"><table width="515" border="0"><tr><td align="left" valign="top" width="172"><a href="ch26_04.htm"><img src="../gifs/txtpreva.gif" alt="Previous" border="0"></a></td><td align="center" valign="top" width="171"><a href="ch26_01.htm">Chapter 26: Plain Old Documentation</a></td><td align="right" valign="top" width="172"><a href="ch27_01.htm"><img src="../gifs/txtnexta.gif" alt="Next" border="0"></a></td></tr></table></div><hr width="515" align="left"><!-- SECTION BODY --><h2 class="sect1">26.5. Documenting Your Perl Programs</h2><p>We hope you document your code, whether or not you're a Random Hacker.If you do, you may wish to include the following sections in your pod:</p><dl><dt><b><tt class="literal">=head1 NAME</tt></b></dt><dd><p>The name of your program or module.</p></dd><dt><b><tt class="literal">=head1 SYNOPSIS</tt></b></dt><dd><p>A one-line description of what your program or module does (purportedly).</p></dd><dt><b><tt class="literal">=head1 DESCRIPTION</tt></b></dt><dd><p>The bulk of your documentation. (Bulk is good in this context.)</p></dd><dt><b><tt class="literal">=head1 AUTHOR</tt></b></dt><dd><p>Who you are. (Or an alias, if you are ashamed of your program.)</p></dd><dt><b><tt class="literal">=head1 BUGS</tt></b></dt><dd><p>What you did wrong (and why it wasn't really your fault).</p></dd><dt><b><tt class="literal">=head1 SEE ALSO</tt></b></dt><dd><p>Where people can find related information (so they can work around your bugs).</p></dd><dt><b><tt class="literal">=head1 COPYRIGHT</tt></b></dt><dd><p>The copyright statement. If you wish to assert an explicit copyright,you should say something like:<blockquote><pre class="programlisting">Copyright 2013, Randy Waterhouse. All Rights Reserved.</pre></blockquote>Many modules also add:<blockquote><pre class="programlisting">This program is free software. You may copy orredistribute it under the same terms as Perl itself.</pre></blockquote></p></dd></dl><p>One caveat: if you're going to put your pod at the end of thefile, and you're using an <tt class="literal">__END__</tt> or <tt class="literal">__DATA__</tt> token, make sureto put an empty line before the first pod directive:<blockquote><pre class="programlisting">__END__=head1 NAMEModern - I am the very model of a modern major module</pre></blockquote>Without the empty line before the <tt class="literal">=head1</tt>, the pod translators willignore the start of your (extensive, accurate, cultured) documentation.</p><!-- BOTTOM NAV BAR --><hr width="515" align="left"><div class="navbar"><table width="515" border="0"><tr><td align="left" valign="top" width="172"><a href="ch26_04.htm"><img src="../gifs/txtpreva.gif" alt="Previous" border="0"></a></td><td align="center" valign="top" width="171"><a href="index.htm"><img src="../gifs/txthome.gif" alt="Home" border="0"></a></td><td align="right" valign="top" width="172"><a href="ch27_01.htm"><img src="../gifs/txtnexta.gif" alt="Next" border="0"></a></td></tr><tr><td align="left" valign="top" width="172">26.4. Pod Pitfalls</td><td align="center" valign="top" width="171"><a href="index/index.htm"><img src="../gifs/index.gif" alt="Book Index" border="0"></a></td><td align="right" valign="top" width="172">27. Perl Culture</td></tr></table></div><hr width="515" align="left"><!-- LIBRARY NAV BAR --><img src="../gifs/smnavbar.gif" usemap="#library-map" border="0" alt="Library Navigation Links"><p><font size="-1"><a href="copyrght.htm">Copyright © 2001</a> O'Reilly & Associates. All rights reserved.</font></p><map name="library-map"> <area shape="rect" coords="2,-1,79,99" href="../index.htm"><area shape="rect" coords="84,1,157,108" href="../perlnut/index.htm"><area shape="rect" coords="162,2,248,125" href="../prog/index.htm"><area shape="rect" coords="253,2,326,130" href="../advprog/index.htm"><area shape="rect" coords="332,1,407,112" href="../cookbook/index.htm"><area shape="rect" coords="414,2,523,103" href="../sysadmin/index.htm"></map><!-- END OF BODY --></body></html>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -