Beefy Boxes and Bandwidth Generously Provided by pair Networks
P is for Practical
 
PerlMonks  

comment on

( [id://3333]=superdoc: print w/replies, xml ) Need Help??
I cannot comprehend how anyone could say that any form of documentation (save that which is incorrect or absent) is "... rude ..." Even private functions should be documented. An example from an API I wrote a while ago (for a largeish company, but not on CPAN, sorry) included documentation for all the private functions because otherwise it was unclear what they did. In this example, the API served to perform exotic math on matrices. One couldn't use simple operators because the operators didn't operate in the exotic way the API required. So private, "behind-the-scenes" functions were made to perform these operations (I suppose we could use some of the newer perl functions with respect to overloading or defining our own operators, but this was a while ago, and those new techniques would still have to be documented).

So let's say there were functions like _alex_weird_add() and _alex_weird_multiply(). Definitely private functions because they performed tasks that weren't "add" or "multiply." I didn't want the user using them, I didn't want them exposed to the rest of the API, but I needed to make sure that somebody down the line (there is always churn in software shops) would be able to read my POD (and in this case my Params::Validate clauses too) and be enlightened.

To suggest that not having the documentation somehow makes the reader of the code ... less in the dark just seems entirely to miss the point of documentation.

--
Tilly is my hero.


In reply to Re^2: The sourcecode *is* the documentation, isn't it? by deprecated
in thread The sourcecode *is* the documentation, isn't it? by dimar

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • 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.
Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others making s'mores by the fire in the courtyard of the Monastery: (6)
As of 2024-03-28 07:52 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found