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.