NAME
OODoc - object oriented production of code documentation
INHERITANCE
OODoc
is a OODoc::Object
SYNOPSIS
use OODoc;
my $doc = OODoc->new(module => 'My Name', version => '0.02');
$doc->processFiles(workdir => $dest);
$doc->prepare;
$doc->create('pod', workdir => $dest);
$doc->create('html', workdir => '/tmp/html');
DESCRIPTION
OODoc stands for "Object Oriented Documentation". The OO part refers to two things: this module simplifies writing documentation for Object Oriented programs, and at the same time, it is Object Oriented itself: easily extensible.
OODoc is a rather new module, but is developed far enough to be useful for most applications. You have the possibility to modify the output of the formatters to your taste using templates, although it is not donfigurable in full extend.
Please contribute ideas. Have a look at the main website of this project at http://perl.overmeer.net/oodoc/.
OVERLOADED
METHODS
Constructors
OODoc->new(OPTIONS)
Option Defined in Default
module <required>
verbose 0
version <required>
. module STRING
The name of the module, as will be shown on many places in the produced manual pages and code. You can use the main package name, or something which is nicer to read.
. verbose INTEGER
Verbosity during the process. The higher the number, the more information will be presented (current useful maximum is 4).
. version STRING
The version number as automatically included in all packages after each package statement and on many places in the documentation.
Inheritance knowledge
$obj->extends([OBJECT])
Attributes
$obj->module
Returns the nice name for the module.
$obj->version
Returns the version string for the module.
Parser
$obj->processFiles(OPTIONS)
Option Defined in Default
manifest 'MANIFEST'
parser 'OODoc::Parser::ExtendedPOD'
select qr/\.(pod|pm)$/
verbose <from object>
workdir <required>
. manifest FILENAME
The manifest file lists all files which belong to this module: packages, pods, tests, etc.
. parser CLASS|OBJECT
The parser CLASS or OBJECT to be used to process the pages.
. select ARRAY|REGEX|CODE
The files which contain documentation to be processed. You can provide a list of filenames as array reference, a REGEX which is used to select names from the manifest file, or a CODE reference which is used to select elements from the manifest (filename passed as first argument). Is your pod real pod or should it also be passed through the parser?
. verbose INTEGER
Tell more about each stage of the processing. The higher the number, the more information you will get.
. workdir DIRECTORY
$obj->selectFiles(WHICH, LIST)
Returns two array references: the first with files to process, and the second with files which do not need to be processed. WHICH comes from processFiles(select) and the LIST are files from a manifest.
Preparation
$obj->expandManuals
Take all manuals, and fill them with the info all the super classes. Some of this data may actually be used when formatting the manual into pages.
$obj->getPackageRelations
Compile all files which contain packages, and then try to find-out how they are related.
$obj->prepare(OPTIONS)
Add information to the documentation tree about inheritance relationships of the packages. prepare
must be called between processFiles() and create().
Option Defined in Default
verbose <from object>
. verbose INTEGER
Formatter
$obj->create(NAME|CLASS|OBJECT, OPTIONS)
Create a manual for the set of manuals read so far. The manuals are produced by different formatters which produce one page at a time. Returned is the formatter which is used: it may contain useful information for you.
The first, optional argument specifies the type of pages to be produced. This can be either a predefined NAME (currently available are pod
and html
representing OODoc::Format::Pod and OODoc::Format::Html respectively), the name of a CLASS which needs to be instantiated, or an instantiated formatter.
Option Defined in Default
append C<undef>
format_options []
manifest <workdir>/MANIFEST
manual_format []
manual_template C<undef>
other_files C<undef>
process_files <formatter dependent>
verbose 0
workdir <required>
. append STRING|CODE
The value is passed on to OODoc::Format::createManual(append), but the behavior is formatter dependent.
. format_options ARRAY
Formatter dependent initialization options. See the documentation of the formatter which will be used for the possible values.
. manifest FILENAME|undef
The names of the produced files are appended to this file. When undef is given, no file will be written for this.
. manual_format ARRAY
Options passed to OODoc::Format::createManual(format_options) when a manual page has to be produced. See the applicable formatter manual page for the possible flags and values.
. manual_template LOCATION
Passed to OODoc::Format::createManual(template), and defines the location of the set of pages which has to be created for each manual page. Some formatters do not support templates and the valid values are formatter dependent.
. other_files DIRECTORY
Other files which have to be copied passed to OODoc::Format::createOtherPages(source).
. process_files REGEXP
Selects the files which are to be processed for special markup information. Other files, like image files, will be simply copied. The value will be passed to OODoc::Format::createOtherPages(process).
. verbose INTEGER
Debug level, the higher the number, the more details about the process you will have.
. workdir DIRECTORY
The directory where the output is going to.
$obj->stats
Returns a string which contains some statistics about the whole parsed document set.
Commonly used functions
$obj->filenameToPackage(FILENAME)
OODoc->filenameToPackage(FILENAME)
$obj->mkdirhier(DIRECTORY)
OODoc->mkdirhier(DIRECTORY)
Manual Repository
$obj->addManual(MANUAL)
$obj->mainManual(NAME)
$obj->manual(NAME)
$obj->manuals
$obj->manualsForPackage(NAME)
$obj->packageNames
DIAGNOSTICS
Error: Cannot compile $parser class
The $parser class does not exist or produces compiler errors.
Error: Parser $parser could not be instantiated
Something went wrong while starting the parser object. Probably there is an other error message which will tell you the exact cause.
Error: cannot copy distribution file $fn to $dest: $!
For some reason, a plain file from can not be copied from your source tree to the location where the distribution is made.
Error: formatter $name has compilation errors: $@
The formatter which is specified does not compile, so can not be used.
Error: manual definition requires manual object
A call to addManual() expects a new manual object (a OODoc::Manual), however an incompatible thing was passed. Usually, intended was a call to manualsForPackage() or mainManual().
Warning: no file $fn to include in the distribution
Probably your MANIFEST file lists this file which does not exist. The file will be skipped for now, but may cause problems later on.
Error: no version specified for module "$name"
Version information will be added to all packages and all manual pages. You need to specify a version and be sure that it changes with each release.
Error: problems compiling $code for package $name: $@
Syntax error in your code, or a problem caused by stripping the file. You can run your test-scripts before the files get stripped as long as you do not use make test
, because that will try to produce manual-pages as well...
Error: requires a directory to write the distribution to
You have to give a value to workdir
. When processing the manifest file, some files must be copied directly to a temporary directory. The packages are first stripped from their pseudo doc, and then written to the same directory. That directory will be the place where make dist
is run later.
Error: requires a directory to write the manuals to
You have to give a value to workdir
, which will be used as top directory for the produced output. It does not matter whether there is already some stuff in that directory.
Error: the produced module needs a descriptive name
Every module needs a name, which will be used on many places in the documentation.
Error: use regex, code reference or array for file selection
The processFiles(select) option is not understood. You may specify an ARRAY, regular expression, or a code reference.
DETAILS
Why use OODoc in stead of POD
POD (Perl's standard Plain Old Document format) has a very simple syntax. POD is very simple to learn, and the produced manual pages look like normal Unix manual pages. However, when you start writing larger programs, you start seeing the weaker sites of POD.
One of the main problems with POD is that is using a visual markup style: you specify information by how it must be presented to the viewer. This in contrast with logical markup where you specify the information more abstract, and a visual representation is created by translation. For instance in HTML defines a I
tag (visual markup italic) and EM
(logical markup emphasis, which will usually show as italic).
The main disadvantage of visual markup is lost information: the formatter of the manual page can not help the author of the documentation to produce more consistent manual pages. This is not a problem for small modules, but is much more needed when programs grow larger.
How does OODoc work
Like with POD, you simply mix your documentation with your code. When the module is distributed, this information is stripped from the files by a parser, and translated into an object tree. This tree is then optimized: items combined, reorganized, etc, to collect all information required to produce useable manual pages. Then, a formatter is called to generate the manual pages.
The parser
The parser reads the package files, and (by default) strip them from all documentation. The stripped files are written to a temporary directory which is used to create the module distribution.
It is possible to use more than one parser for your documentation. On this moment, there is only one parser implemented: the Markov parser, named after the author. But you can add your own parser, if you want to. Within one module, different files can be parsed by different parsers.
The parser produces an object tree, which is a structured representation of the documentation. The tree is parser independent, and organized by manual page.
Collecting relations
The second phase of the manual page generation process figures out the relations between the manual pages. It collects inheritance relations and other organizational information which is to be used by the manual page generators.
The formatter
The final phase can be called more than once: based on the same object tree, documents can be produced in various formats. The initial implementation produces POD and HTML.
Getting Started
To use OODoc, you need to create a scripts which helps you producing the distribution of your module. The simpest script look like this:
use OODoc;
my $dist = '/tmp/abc';
my $doc = OODoc->new
( module => 'E-mail handling'
, version => '0.01'
);
$doc->processFiles(workdir => $dist); # parsing
$doc->prepare; # collecting
$doc->create('pod', workdir => $dist); # formatting to POD
The default parser will be used to process the files, see OODoc::Parser::Markov for its syntax. The formatter is described in OODoc::Format::Pod.
Once you have this working, you may decide to add options to the calls to adapt the result more to your own taste.
REFERENCES
See the OODoc website at http://perl.overmeer.net/oodoc/ for more details.
COPYRIGHTS
Module version 0.06. Written by Mark Overmeer (mark@overmeer.net). See the ChangeLog for other contributors.
Copyright (c) 2003 by the author(s). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.