NAME

OODoc - object oriented production of software documentation

INHERITANCE

OODoc
  is an OODoc::Object

SYNOPSIS

use OODoc;
my $doc = OODoc->new(distribution => 'My Name', version => '0.02');
$doc->processFiles(workdir => $dest);
$doc->finalize;
$doc->formatter('pod', workdir => $dest)->createPages;
$doc->formatter('html', workdir => '/tmp/html')->createPages;

or use the oodist script, included in this distribution (advised).

DESCRIPTION

"OODoc" stands for "Object Oriented Documentation": to create better manual-pages in HTML and Perl's POD format than produced by the standard offerings of the Perl tool-chain.

Do not forget to read the "DETAILS" section (further down on this manual-page) to get started. Please contribute ideas. Have a look at the main website of this project at https://perl.overmeer.net/oodoc/. That is also an example of the produced html output (we are working on nicer visuals)

Extends "DESCRIPTION" in OODoc::Object.

OVERLOADED

Extends "OVERLOADED" in OODoc::Object.

overload: '==' and '!=' (numeric comparison): Inherited, see "OVERLOADED" in OODoc::Object
overload: 'bool': Inherited, see "OVERLOADED" in OODoc::Object

METHODS

Extends "METHODS" in OODoc::Object.

Constructors

Extends "Constructors" in OODoc::Object.

$class->new(%options)

Create this general manager object. When you use the oodist script, these parameters are read from the configuration in Makefile.PL (actually MYMETA.json). Improves base, see "Constructors" in OODoc::Object

-Option      --Default
 distribution  <required>
 project       $distribution
 version       <from version or VERSION file>

distribution => STRING: The name of the package, as released on CPAN.
project => STRING: A short description of the $distribution, 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.
version => STRING: The version number as automatically included in all packages after each package statement and on many places in the documentation. By default the current directory is searched for a file named version or VERSION which contains a number.

Attributes

Extends "Attributes" in OODoc::Object.

$obj->distribution(): Returns the nice name for the distribution.
$obj->project(): Returns the general project description, by default the distribution name.
$obj->unique(): Inherited, see "Attributes" in OODoc::Object
$obj->version(): Returns the version string for the distribution.

Manual Repository

Extends "Manual Repository" in OODoc::Object.

$obj->addManual($manual): Inherited, see "Manual Repository" in OODoc::Object
$obj->findManual($name): Inherited, see "Manual Repository" in OODoc::Object
$obj->mainManual($name): Inherited, see "Manual Repository" in OODoc::Object
$obj->manuals(): Inherited, see "Manual Repository" in OODoc::Object
$obj->manualsForPackage($name): Inherited, see "Manual Repository" in OODoc::Object
$obj->packageNames(): Inherited, see "Manual Repository" in OODoc::Object
$obj->publicationIndex(): Inherited, see "Manual Repository" in OODoc::Object
$obj->publish(\%options): Inherited, see "Manual Repository" in OODoc::Object

Parser

$obj->processFiles(%options)

Extract the documentation from the selected files.

-Option      --Default
 distribution  <from main OODoc object>
 manifest      "$source/MANIFEST"
 notice        ''
 parser        OODoc::Parser::Markov
 select        qr/\.(pod|pm)$/
 skip_links    []
 source        '.'
 version       <from source directory or OODoc object>
 workdir       undef

distribution => NAME

Useful when more than one distribution is merged into one set of documentation.

manifest => $file

The MANIFEST $file lists all files which belong to this distribution: packages, pods, tests, etc. before the new pod files are created.

notice => $text

Include the $text (which may consist of multiple lines) to each of the pm files. This notice usually contains the copyright message.

parser => CLASS|$name|$parser

The parser CLASS or $parser 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?

skip_links => ARRAY|STRING|REGEXP

Passed to OODoc::Parser::new(skip_links).

source => $directory

The location where the files are located. This is useful when you collect the documentation of other distributions into the main one. Usually in combination with an undefined value for workdir.

version => STRING

The version of the distribution. If not specified, the source directory is scanned for a file named version or VERSION. The content is used as version value. If these do not exist, then the main OODoc object needs to provide the version.

To make Makefile.PL option VERSION_FROM to work with this seperate version file, that line should contain something like

our $VERSION = 3.14;

workdir => $directory

Specify the $directory where the stripped pm-files and the pod files will be written to. Probably the whole distribution is collected on that spot.

When the processed files are not part of this distribution, then then do not specify this option: knowledge is built, but not included in the release.

$obj->selectFiles($filter, @files)

Split the @files into two sets: the first with @files to process, and the second with @files which do not need to be processed. The selecting $filter comes from processFiles(select) and the @files are originally read from a MANIFEST. Returned are two ARRAY (references).

Actions

$obj->finalize(%options)

[3.01] After all documentation fragments have been read via processFiles(), the pages need to be composed together. For instance, inheritance and final cleanups are due here.

$obj->formatter($name|$class|$object, %options)

[2.03] 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 $object.

You can also pass many options which are passed to (the effective extension of) OODoc::Format::createPages().

-Option  --Default
 manifest  workdir/MANIFEST
 workdir   <required>

manifest => FILENAME|undef: The names of the produced files are appended to this file content. When undef is given, no file will be written for this.
workdir => $directory: The $directory where the output is going to.

$obj->getPackageRelations()

Compile all files which contain packages, and then try to find-out how they are related.

$any->mkdirhier($directory)

Creates this $directory and all its non-existing parents.

$obj->stats()

Returns a string which contains some statistics about the whole parsed document set.

DETAILS

OODoc

The "OO" part of the name refers to two things: this module simplifies writing documentation for Object Oriented programs. At the same time, it is Object Oriented itself: easily extensible. It can be used to integrate manual-pages from many distributions into one homogeneous set. OODoc has been used for small single package upto very large sets of modules, like the MailBox suite.

Adding logical markup

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 standard Unix manual pages. However, when you start writing larger programs, you start seeing the weaker aspects 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 an application. For instance, HTML defines an <I> tag as visual markup Italic, and <EM> as logical markup for EMphasis, which will usually show in italic.

The main disadvantage of visual markup is limited expression: the formatter of the manual page can not help the author of the documentation to produce more consistent and complete manual pages. This is not a problem for small distributions, but is much more needed when code grows larger.

Application

This module can be used directly, but you may also use the oodist script which comes with this distribution. That command will also help you with your whole distribution release process.

The documentation syntax can be changed by configuring the provided parser or adding a new one. The OODoc::Parser::Markov parser extends standard POD, which uses visual markup, with logical markup tags.

The output is produced by formatters and exporters. The current implementation contains three POD formatters, one HTML formatter, and a JSON exporter.

How OODoc works

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 in real POD or HTML. You may also use an exporter to serialize that tree (into JSON).

My-Dist -------+                      +--formatter--> POD
My-Other-Dist -|--parser--> DocTree --|--formatter--> HTML
Even-More -----+                      +--exporter---> JSON/HTML

The parser

The parser reads the package files, and (by default) strips them from all documentation fragments. The stripped pm files are written to a temporary directory which is used to create the distribution release. Existing pod files will also be consumed, but published untouched.

The parser produces an object tree, which is a structured representation of the documentation. That tree is parser independent, and organized by manual page.

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. You can add your own parser, if you prefer to. Within one distribution, different files may be parsed by different parsers.

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.

Links are being checked. The Markov parser let you refer to subroutines and even documented options within a sub.

Information of super-classes is merged: sections, methods, method options and their defaults. Methods are sorted by name per ((sub)sub)section.

formatter

The final phase can be called more than once: based on the same object tree, documents can be produced in various formats. The current implementations produce POD and HTML.

More details in the OODoc::Format base-class.

exporters

You may also export the documentation tree to be used with your own separate application. At this moment, that dump will be made in JSON with HTML-formatted text fragments only.

More details in the OODoc::Export base-class.

Release process

OODoc, as document generator, will need to be integrated into your software release process.

do it yourself

To use OODoc, you need a script which helps you producing the distribution of your module. The simpest script looks like this:

use OODoc;
my $dist = '/tmp/abc';
my $doc  = OODoc->new(
  distribution => 'E-mail handling',
  version      => '0.01',
);

$doc->processFiles(...);  # parsing
$doc->finalize(...);      # collecting
$doc->formatter('pod', ...)->createPages(...);
                          # 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.

use oodist

This distribution comes with a script named oodist, which automates most steps of your release process (to CPAN). To start using OODoc with your existing distribution, simply run this:

1. go to the root directory of your module
2. run 'oodist'
3. follow the instructions to configure oodist
4. run 'oodist -v'

This should take you more than a few minutes. When the output looks fine, then start playing with the advantages of the Markov extended POD syntax.

Checking the produced manual pages

To test the document production for My::Module, try (on UNIX/Linux)

pod2man $dist/lib/My/Module.pod | man -l -

DIAGNOSTICS

Info: * collect package relations

Info: * create inheritance chapters

Info: * expand manual contents

Info: * finalize each manual

Error: cannot compile $pkg class: $err

The $pkg parser class does not exist or produces compiler errors.

Fault: cannot copy distribution file $from to $to: $!

For some reason, a plain file can not be copied $from your source tree $to the location where the distribution is made.

Fault: cannot create $dir: $!

Fault: cannot read distribution version from file $file: $!

Fault: cannot read version from $file: $!

A $file named version or VERSION was found to contain the distribution version, but not accessible.

Info: compiling all packages

Info: detect inheritance relationships

Warning: errors from $manual: $err

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: formatter() requires a directory to write the manuals to

You have to provide 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: 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 $file 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 distribution $dist

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, or create a file named version or VERSION which contains that data.

Error: parser $name 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: requires a directory to write the distribution to

You have to give a value to workdir, which may be undef. This option is enforced to avoid the accidental omission of the parameter.

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: the produced distribution needs a project description

Error: there is no version defined for the source files

Each manual will need a version number. There are various ways to specify one. For instance, create a file named version or VERSION in the top source directory of your distribution, or specify a version as argument to OODoc::new() or OODoc::processFiles().

Error: use regex, code reference or array for file selection, not $type

The processFiles(select) option is not understood. You may specify an ARRAY, regular expression, or a CODE reference.

LICENSE

For contributors see file ChangeLog.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

To install OODoc, copy and paste the appropriate command in to your terminal.

cpanm

cpanm OODoc

CPAN shell

perl -MCPAN -e shell
install OODoc

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)