Perldoc: The Need for a Better Documentation System
Posted in perl 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:
- ability to generate standardized docs listing params, results, exceptions, etc. like Javadoc,
- ability to auto-generate lists of files, classes and methods like rdoc, and
- 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.
This sounds a lot like Mark Overmeer’s OODoc, http://search.cpan.org/~markov/OODoc-1.04/lib/OODoc.pod
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.
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.
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.
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….
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.
@John FYI.Comments to this blog do not get submitted if they are previewed first.(something to fix in your free time ;))