Object Oriented Documentation: Extending Pod to generate HTML

Object Oriented Documentation: Extending Pod to generate HTML

By Mark Overmeer (‎markov‎) from Arnhem.pm, Amsterdam.pm
Date: Friday, 25 July 2003 14:30
Duration: 20 minutes
Language:

Everyone who was has created a module with a reasonable set of packages
has experienced the limitations of POD. The syntax of POD is simple
to learn, and documenting a single package with POD is in reach of even
the worst programmers.

However, POD has serious limitations. You may argue about the common
syntax of POD, but that's matter of taste and outside the scope of this
talk. Real limitations of POD are:
+ visual in stead of logical markup, so formatters can not be smart
+ no support for object orientation
+ copy-paste parts needed between packages within the same module

As author of a few large Object Oriented modules, I have hit the
limitations of POD too often. The usefulness and quality of the
documentation is rapidly decreasing when the program grows. After two
private implementations for a solution, there now is a public release for
"Object Oriented Documentation", named OODoc.

OODoc adds logical markup to POD. When a distribution is created, real
POD and HTML can be produced from this extended POD. The connection is
made between "as simple as possible" for the developer of the code, and
"as browsable as possible" for the user of the module.

The basics of OODoc are explained by some examples, as for instance
can be seen at http://perl.overmeer.net/oodoc/html/