hm... *grumble grumble grumble* pod is an amazing tool for
giving excellent "birds eye view" documentation, however I
am going to state my rather (probably) unpopular opinion,
that it is woefully underqualified to do code documentation
and reference documentation (which I belive javadoc has as
a forte.) I think this stems from the very different backgrounds
that perl and java have, in the "standard" perl problem, the
solution is small enough that one person can understand it,
and someone else can learn it with little effort (as long
as they are a qualified perl programmer.) Java never had
that idea, i have worked on java projects with well over
1000 class files where no one person understood well the
entire project, and very few people even understood where
there part of the machine fit. When you are having to
write documentation for such an enviroment, a more low
level API-ish documentation (such as javadoc) is the logical
progression.
As perl grows and expands and begins to be used in large scale
software development, this is going to become more and more
of an issue. (Before I get flamed, by large scale development
i mean projects with a very large function point analysis score,
an OO heirarchy with multiple levels of inheritance, and something
with a great many interfaces.) It may be that Perl ends up
inheriting 2 documentation systems, POD for birds eye view,
and (insert_name_here) for API and low level documentation.
Does anyone with more experience want to step up to the
plate, and give this a more formal treatment?
and in closing... neither one of those are really good
examples of literate programming... read the knuth book,
you'll see what I mean :)
Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
Read Where should I post X? if you're not absolutely sure you're posting in the right place.
Please read these before you post! —
Posts may use any of the Perl Monks Approved HTML tags:
- a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
| |
For: |
|
Use: |
| & | | & |
| < | | < |
| > | | > |
| [ | | [ |
| ] | | ] |
Link using PerlMonks shortcuts! What shortcuts can I use for linking?
See Writeup Formatting Tips and other pages linked from there for more info.