Pod::Classdoc

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