That would be really nice, yes. Unfortunately for would-be authors of such tools, Perl isn't well-suited to such interrogation. This is partially because the syntactic flexibility allows people to write really bad code: the kind which only perl can really parse.

So, you have to start with the assumption that the code follows some kind of guidelines or best practices. That's a big assumption -- after all, if the programmer were disciplined enough to follow good coding practices, she would have already documented well, and this issue wouldn't exist.

Also, consider that things like required arguments are not language-native. Subroutines are not declared in a way that says 'arguments foo, bar, and baz are required, and aleph and beth are optional'. Sometimes there are prototypes, but they are generally avoided (and for good reason). Some scripts will not even have subroutines, since it isn't required by Perl.

All of these things are positive from a developer standpoint: they make Perl a very powerful and flexible tool. From the standpoint of trying to automatically determine how given code functions, it's a thorn.

<-radiant.matrix->
A collection of thoughts and links from the minds of geeks
The Code that can be seen is not the true Code
"In any sufficiently large group of people, most are idiots" - Kaa's Law

In reply to Re: Documenting Perl Scripts by radiantmatrix
in thread Documenting Perl Scripts by ajcannon48

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


  • 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:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.