SUMMARY: CONSTR | METHOD DETAIL: CONSTR | METHOD

Class Pod::Classdoc

Known Subclasses:
Pod::Classdoc::ForProjectTOC

Generate javadoc-like class documentation from embedded POD. Uses PPI::Find to locate POD, packages, and methods, then processes the extracted POD into a javadoc-ish HTML format. Classdoc POD is defined within =begin classdoc and =end classdoc sections. Each such section is associated with its immediately succeding package or method statement, unless the @xs directive is specified, in which case the classdoc is assumed to be for an external (e.g., XS) method. Multiple external method classdoc sections may be specified within a single =pod ... =cut section, with the final such classdoc section associated with any trailing method definition.

Author:
Dean Arnold
Since:
2007-Jun-10
See Also:
PPI,
PPI::Find,
"How to Write Doc Comments for the Javadoc Tool"

Class instances are hash references.

Unless otherwise noted, $self is the object instance variable.

Constructor Summary
new($path, $title, $verbose)
           Creates a new empty Pod::Classdoc object.

Method Summary
add($txt, $file)
           Scan the provided text for Perl packages, adding the packages to the current collection of classes.
clear()
           Clear this object.
getFrameContainer($home)
           Generate a toplevel container document for the TOC and classdoc frames.
getTOC(@order)
           Generate a table of contents document for the current collection of classdocs as a nested HTML list.
makeClassPath($class)
           Generate fully qualified pathname of output classdoc file for a given package name.
new()
open($path, $pkg)
           Load the specified package file.
openProject(@projects)
           Load all the package files within a specified project directory.
path($path)
           Get or set the output directory path for rendered documents.
render($use_private)
           Render the loaded packages into classdocs.
writeClassdocs($use_private)
           Write out the documents for the current collection of classdocs.
writeFrameContainer($container, $home)
           Write out a toplevel container document for the TOC and classdoc frames.
writeTOC(@order)
           Write out an table of contents document for the current collection of classdocs as a nested HTML list.

Constructor Details

new

new($path, $title, $verbose)

Creates a new empty Pod::Classdoc object.

Parameters:
$path - (optional)directory path for output documents; default is './classdocs'
$title - (optional)title string to use for head of classdocs
$verbose - (optional)if true, enables diagnostic output (default false)
Returns:
a new Pod::Classdoc object

Method Details

add

add($txt, $file)

Scan the provided text for Perl packages, adding the packages to the current collection of classes. When a package is located, it is scanned for its inherited classes and classdoc'd methods.

Parameters:
$txt - the package text as either a scalar string, or an arrayref of the lines of the package
$file - (optional)full path of source file
Returns:
the PPI::Document object generated from the input text

clear

clear()

Clear this object. Removes all currently loaded packages.

Returns:
this object

getFrameContainer

getFrameContainer($home)

Generate a toplevel container document for the TOC and classdoc frames. Assumes the TOC is named 'toc.html'.

Parameters:
$home - (optional)pathname of a toplevel document to be included in index
Returns:
the frame container document

getTOC

getTOC(@order)

Generate a table of contents document for the current collection of classdocs as a nested HTML list. Caller may optionally specify the order of classes in the menu.

Parameters:
@order - (optional)list of packages in the order in which they should appear in TOC; if a partial list, any remaining packages will be appended to the TOC in alphabetical order
Returns:
the TOC document

makeClassPath

makeClassPath($class)

Generate fully qualified pathname of output classdoc file for a given package name. Also creates the path if needed.

Parameters:
$class - package name to be resolved to output classdoc file
Returns:
the fully qualified pathname to the classdocs for $class, with a '.html' qualifier.

new

new()

 


open

open($path, $pkg)

Load the specified package file.

Parameters:
$path - path to the package file.
$pkg - Perl name of the package
Returns:
the PPI::Document object generated from the input file

openProject

openProject(@projects)

Load all the package files within a specified project directory. Recurses into subdirectories as needed.

Parameters:
@projects - list of pathnames of root project directories
Returns:
this Pod::Classdoc object

path

path($path)

Get or set the output directory path for rendered documents.

Parameters:
$path - (optional)root directory where classdocs are to be written; if not provided, a Get operation is executed @returns for a Get operation, the current output path; for a Set operation, the prior output path

render

render($use_private)

Render the loaded packages into classdocs. Creates subdirectories for subordinate classdocs as needed. Package files containing multiple package definitions will result in individual files for each package.

Parameters:
$use_private - (optional)include private methods. By default, only public methods are included in the output; setting this flag causes any documented private methods (methods beginning with an underscore) to be included as well. Note that constructors are always considered public. @returns on success, a hashref mapping classnames to an arrayref of the classdoc formatted output, the input source file name and line number of the class's associated classdoc'd package definition, and a hashref mapping method names to an arrayref of source file name and linenumber; undef on failure, with error message in $@

writeClassdocs

writeClassdocs($use_private)

Write out the documents for the current collection of classdocs. Renders the current set of classdocs before writing.

Parameters:
$use_private - (optional)include private methods. By default, only public methods are included in the output; setting this flag causes any documented private methods (methods beginning with an underscore) to be included as well. Note that constructors are always considered public.
Returns:
undef on failure, with error message in $@; otherwise, a hashref mapping classnames to an arrayref of the full pathname of the classdoc formatted output file, the input source file name and line number of the class's associated classdoc'd package definition, and a hashref mapping method names to an arrayref of source file name and linenumber.

writeFrameContainer

writeFrameContainer($container, $home)

Write out a toplevel container document for the TOC and classdoc frames. Assumes the TOC is named 'toc.html'.

Parameters:
$container - name of output file without path; path is taken from the path specified via new() or path()
$home - (optional)pathname of a toplevel document to be included in index
Returns:
this object on success, undef on failure, with error message in $@

writeTOC

writeTOC(@order)

Write out an table of contents document for the current collection of classdocs as a nested HTML list. The output filename is 'toc.html'. The caller may optionally specify the order of classes in the menu.

Parameters:
@order - (optional)list of packages in the order in which they should appear in TOC; if a partial list, any remaining packages will be appended to the TOC in alphabetical order
Returns:
this object on success, undef on failure, with error message in $@

Generated by POD::ClassDoc 1.01 on Sat Aug 18 11:02:01 2007