Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • by ziggy (25) on 2002.05.09 10:58 (#8195) Journal
    The ability to use /// for inline XML documentation is nifty.
    I'm about as skeptical about this one as I was two years ago when it was first announced.

    Consider XML as a reasonable default syntax, much like the GPL is a reasonable default license (if you intend all users of your software to be on an even playing field). That's default, not universal. Over the years, I've found that the mindset when I'm writing a document (in XML, LaTeX, Pod, HTML, whatever), is different than the mindset when I'm programming.

    There's a benefit to using structured documentation conventions within code. But most comments aren't structured (and shouldn't be, or else they'd be documentation, not comments). The best solution I've seen is something like Pod, where the structure is expressly intuited (there are always some improvements that could be made, of course). Also, Pod works quite well as a documentation format that works when intermingled with the code, preceding or following the code (especially after __END__).

    • I think a more universal literate programming [literateprogramming.com] system is needed.

      All the existing ones tend to have some problem with some aspect (typically they're too tied to a particular language for either the doco part of the code part).
      --
        ---ict / Spoon