If you need to look at the source code of a module, the author failed in writing their documentation. If Perl was C, it would be harder to not document your code since the parameters and return value can't be hidden. In Perl both are hidden. In writing docs, I basically address the following questions.
- What are the parameters?
- how many?
- variable parameters?
- what parameter validation is performed?
- how is error condition indicated? die/exceptions? warn? $!? return value?
- What is the return value? list or scalar?
- what are the possible errors (if possible, sometimes they come from something your module calls)?
- common ways to leak resources
- common mistakes
- does undef as a parameter have special meaning?
- what the function DOES NOT do
- alternatives in same module, other modules or perl language
- if XS and wrapping a C lib, situations that create unavoidable crashes or bugs in the C lib you as the module author hit
-
Are you posting in the right place? Check out Where do I post X? to know for sure.
-
Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
<code> <a> <b> <big>
<blockquote> <br /> <dd>
<dl> <dt> <em> <font>
<h1> <h2> <h3> <h4>
<h5> <h6> <hr /> <i>
<li> <nbsp> <ol> <p>
<small> <strike> <strong>
<sub> <sup> <table>
<td> <th> <tr> <tt>
<u> <ul>
-
Snippets of code should be wrapped in
<code> tags not
<pre> tags. In fact, <pre>
tags should generally be avoided. If they must
be used, extreme care should be
taken to ensure that their contents do not
have long lines (<70 chars), in order to prevent
horizontal scrolling (and possible janitor
intervention).
-
Want more info? How to link
or How to display code and escape characters
are good places to start.
|
