Beefy Boxes and Bandwidth Generously Provided by pair Networks
more useful options
 
PerlMonks  

comment on

( [id://3333]=superdoc: print w/replies, xml ) Need Help??
Good meditation! Here is my wishlist:
  • Moose made part of the standard distro, and a perl switch to turn it on.
  • A totally new documentation format, can we all just agree pod sucks... It's so old and dated. It comes off as a markup that was made for documenting the intention of code as to eliminate the need to comment-explain in source. It is instead used for writing verbose tutorials that sit uncomfortable and awkwardly in the middle of source.

    My solution would be some sort of wiki-powered pod, to which perldoc could sync to and read from the online Wiki. I'm not saying this wiki needs to be anon; and, I'm not putting any stipulations on its implementation. It should probably start off as an RFC right about now. Community powered, centralized documentation would ensure that perl stays a leg up on the doc component of the language, and it would alleviate the devs needs to doc everything. So often I find myself debunking bad docs, and then too lazy to push up an elaborate patch in the current sub-par format. I should clarify the word "doc" in this paragraph is a reference to tutorials, how-tos, use cases etc., not mere internal explanation. It is also my personal opinion that Textile is a superior markup to pod.

    As to the archaic pod, I think it serves a good purpose documenting code, but one feature I would like to see in it is the ability to further notate what the code chuck is you're documenting. I don't want to have to keep a sub in sync, inside of a pod block.

    Bottom line: Tutorials should not be in pod. They are not pod material, they are too often an interference to the terseness of perl. Put them online, and let's let the community take a crack at detailing the use of the code, and leave POD to the internal function of the code and dev-notes, i.e., what in most other languages is known as *comments* (as compared to "the documentation").

So thats my two cents, the two things I see perl5 most inept in can be almost totally fixed with the inclusion of Moose, and a better documentation system. (though I know how well accepted any criticism of pod will be)



Evan Carroll
www.EvanCarroll.com

In reply to Re: what would you like to see in perl5.12? by EvanCarroll
in thread what would you like to see in perl5.12? by ysth

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 wandering the Monastery: (7)
As of 2024-04-23 11:07 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found