perl icon

Perldoc: The Need for a Better Documentation System

Posted in Sun, 25 Jan 2009 08:51:00 GMT

Continuing the thread of useful projects for Perl, I think it would be very beneficial to enhance Perl's relatively unstructured documentation system (POD) to bring it up to par with other languages today, e.g. Java and possibly others. Structured documentation should enable many benefits to speed development that I've long been a fan of including the following:

  1. ability to generate standardized docs listing params, results, exceptions, etc. like Javadoc,
  2. ability to auto-generate lists of files, classes and methods like rdoc, and
  3. ability to auto-display required parameters like in Visual Studio 2008.

I recently used C# and Visual Studio 2008 for the first time and the auto-display of parameters in the IDE made development much more efficient with a new and unfamiliar language / API. It's something I'd like to see integrated into a Perl IDE, e.g. Eclipse/EPIC, Padre, ActiveState Komodo, etc.

A new documentation system like this for Perl may be easier to build off of Moose which could make it attractive as a Tim Toady Bicarbonate project. Some of the benefits of Javadoc and lessons from C# XML doc can be seen in this thread: C# documentation comments: useless?

Ideally, this effort could be headed up by a TPF or EPO working group consisting of multiple people and organizations including people with interest in documentation and IDEs, e.g. developers or product managers from the various Perl IDE products.

del.icio.us:Perldoc: The Need for a Better Documentation System digg:Perldoc: The Need for a Better Documentation System reddit:Perldoc: The Need for a Better Documentation System spurl:Perldoc: The Need for a Better Documentation System wists:Perldoc: The Need for a Better Documentation System simpy:Perldoc: The Need for a Better Documentation System newsvine:Perldoc: The Need for a Better Documentation System blinklist:Perldoc: The Need for a Better Documentation System furl:Perldoc: The Need for a Better Documentation System fark:Perldoc: The Need for a Better Documentation System blogmarks:Perldoc: The Need for a Better Documentation System Y!:Perldoc: The Need for a Better Documentation System smarking:Perldoc: The Need for a Better Documentation System magnolia:Perldoc: The Need for a Better Documentation System segnalo:Perldoc: The Need for a Better Documentation System

7 comments

Comments

  1. Bernhard.Schmalhofer@gmx.de said about 1 hour later:

    This sounds a lot like Mark Overmeer’s OODoc, http://search.cpan.org/~markov/OODoc-1.04/lib/OODoc.pod

  2. John Wang said about 10 hours later:

    I took a quick look and OODoc (“Object Oriented Documentation”) looks promising from the example HTML output:

    http://perl.overmeer.net/oodoc/html/index.html

    I think enhanced documentation is an area where a recommendation from an authoritative group would help adoption, either from EPO or TPF. Would OODoc be a good candidate to recommend or to use as a starting point?

    I did some searches on OODoc and there doesn’t seem to be much buzz in the way of use Perl, Perl Buzz, TPF, etc. I did find the following use Perl post by melopt but more discussion may be warranted.

    http://use.perl.org/comments.pl?sid=14982&;cid=23258

    Once a documentation system received a recommendation, more people would start using it and it could be integrated with IDEs and websites like the rdoc one. Integration with IDEs and easier to navigate HTML docs are important community-wide benefits that are made possible with a more structured doc system. To get here, some agreement and an authoritative recommendation as a best practice would be very helpful.

  3. Adam Kennedy said 1 day later:

    Rule 1 of Your Documentation Format.

    At this point, with 15,000 modules and 20,000,000 lines of code, it needs to be able to bootstrap incrementally. It needs to have value even when only a dozen or so modules use it.

    Anything that requires a substantial percentage of CPAN to use it to get off the ground is going to be a no go.

  4. Anon said 1 day later:

    The Python community has been using reST (part of their docutils package) with much success. It’s much easier to write in than POD, IMO.

    If you want to help Perl, I’d suggest:

    1. Write a reST processor in Perl (a la docutils)

    2. Write a pod2rest conversion tool.

    3. Come up with some convention for doc generating tools to use when generating docs from Perl modules.

    Yes, I realize that POD is entrenched, and that Damian has even written the new and improved Pod already for Perl 6, but it’s still not nearly as pretty or comfortable to write in as reST.

  5. John Wang said 1 day later:

    My recent renewed interest has been due to running across the hints feature which is called Context Assist in Eclipse and Intellisense in VS2k8. However, after after looking into this some more, I may have jumped to the wrong conclusion and this feature may not be based on docs as I thought. I still think a more structured doc system will help but getting to Context Assist may use a different path….

  6. Sumeet Pareek said about 1 month later:

    I just added this same comment but it did not appear in the thread nor did I get any moderation message. Hence reposting :P

    I have earlier written code in java and php. Only recently I have been using a lot of perl for a HUGE project. My curiosity about the commenting structure for perl to generate automated docs landed me to this page.

    There is certainly a need for having a structure defined for Perl (on the lines of javadoc?) and a module to generate documentation out of them. Whatever be the means to achieve this, if there is a way ‘perl noob’ can contribute – count on me. Will be educating myself better about who takes care of developing perl, maintaining module repository et al rest of the week.

  7. Sumeet Pareek said about 1 month later:

    @John FYI.Comments to this blog do not get submitted if they are previewed first.(something to fix in your free time ;))

(leave url/email »)

   Comment Markup Help Preview comment