NAME

OODoc::Manual - one manual about a package

INHERITANCE

OODoc::Manual
  is an OODoc::Object

SYNOPSIS

my $doc    = OODoc->new(...);
my $manual = OODoc::Manual->new(name => ..., source => ...);

$doc->manual($manual);
my @manual = $doc->manualsForPackage('Mail::Box');

print $manual->name;
print $manual->package;

DESCRIPTION

The OODoc::Manual object contains information of a singel manual page. More than one manual can be related to a single package.

Extends "DESCRIPTION" in OODoc::Object.

OVERLOADED

Extends "OVERLOADED" in OODoc::Object.

overload: cmp

String comparison takes place between a manual name and another manual name which may be a manual object or any other string or stringifyable object.

example:

if($manual eq 'OODoc') ...
if($man1 eq $man2) ...
my @sorted = sort @manuals;    # implicit calls to cmp

overload: stringification

Used in string context, a manual produces its name.

METHODS

Extends "METHODS" in OODoc::Object.

Constructors

Extends "Constructors" in OODoc::Object.

OODoc::Manual->new(%options)

-Option      --Default
 distribution  <required>
 package       <required>
 parser        <required>
 pure_pod      <false>
 source        <required>
 stripped      undef
 version       <required>

distribution => STRING
package => STRING: The name of the package which is described by this manual.
parser => OBJECT: The parser which produces this manual page. This parameter is needed to be able to low-level format the text blocks.
pure_pod => BOOLEAN: Some documentation is stored in files which look like a module, but do not contain any code. Their filenames usually end with .pod.
source => STRING: The file where the manual was found in, or in some cases some other string which explains where the data came from.
stripped => STRING: The file where the stripped code is written to.
version => STRING

Attributes

$obj->distribution(): Returns the distribution which includes this manual.
$obj->isPurePod(): Returns whether this package has real code related to it.
$obj->package(): Returns the package of the manual.
$obj->parser(): Returns the parser which has produced this manual object.
$obj->source(): Returns the source of this manual information.
$obj->stripped(): The name of the produced stripped package file.
$obj->version(): Returns the version of this manual information.

Collected

$obj->chapter($name|$object)

When a $name (a string) given, the chapter with that name is returned, or undef when it is not known. With an $object, that object is added to the list of chapters.

$obj->chapters( [$chapters] )

Returns the ordered list of chapter object for this manual.

$obj->diagnostics(%options)

All diagnostic messages of all chapters for this manual together.

-Option--Default
 select  []

select => ARRAY: Select only the diagnostic message of the specified types (case insensitive). Without any type, all are selected.

$obj->examples()

All examples of all chapters within this manual together, especially useful for counting.

example:

print scalar $manual->examples;

$obj->name()

Returns the name of the manual, which is found in the NAME chapter.

$obj->subroutine($name)

Returns the subroutine with the specified $name as object reference. When the manual is part of a package description which is spread over multiple manuals, then these other manuals will be searched as well.

$obj->subroutines()

All subroutines of all chapters within this manual together, especially useful for counting.

example:

print scalar $manual->subroutines;

Inheritance knowledge

Extends "Inheritance knowledge" in OODoc::Object.

$obj->all($method, $parameters)

Call OODoc::Text::Structure::all() on all chapters, passing the $method and $parameters. In practice, this means that you can simply collect kinds of information from various parts within the manual page.

example:

my @diags = $manual->all('diagnostics');

$obj->extends( [$object] )

Inherited, see "Inheritance knowledge" in OODoc::Object

$obj->extraCode()

Returns a list of manuals which contain extra code for this package.

$obj->inherited($subroutine|$option)

Returns whether the $subroutine or $option was defined by this manual page, or inherited from it.

$obj->ownSubroutines()

Returns only the subroutines which are described in this manual page itself. subroutines() returns them all.

$obj->realizers( [$packages] )

Returns a list of packages which can realize into this object using Object::Realize::Later magic. When $packages (names or objects) are specified, they are added first.

$obj->realizes( [$package] )

Returns the class into which this class can be realized. This is a trick of the Object::Realize::Later module. The $package (name or object) will be set first, if specified.

$obj->subClasses( [$packages] )

Returns the names of all sub-classes (extensions) of this package. When $packages (names or objects) are specified, they are first added to the list.

$obj->superClasses( [$packages] )

Returns the super classes for this package.

Provided $packages (names or objects) will be added to the list of superclasses first.

Processing

$obj->collectPackageRelations()

$obj->createInheritance()

Create the text which represents the inheritance relationships of a certain package. More than one MANUAL can be defined for one package, and will each produce the same text. The returned string still has to be cleaned-up before inclusion.

$obj->expand()

Add the information of lower level manuals into this one.

$obj->mergeStructure(%options)

Merge two lists of structured text objects: "this" list and "super" list. The "this" objects are defined on this level of inheritance, where the "super" objects are from an inheritence level higher (super class). The combined list is returned, where the inherited objects are preferably included before the new ones.

Merging is a complicated task, because the order of both lists should be kept as well as possible.

-Option   --Default
 container  <required>
 equal      sub {"$_[0]" eq "$_[1]"}
 merge      sub {$_[0]}
 super      []
 this       []

container => OBJECT: The object which administers this level of documentation nesting, which may be a manual, chapter, and such.
equal => CODE: Define how can be determined that two objects are the same. By default, the stringification of both objects are compared.
merge => CODE: What to call if both lists contain the same object. These two objects will be passed as argument to the code reference. By default, the second gets ignored.
super => ARRAY
this => ARRAY

$obj->mostDetailedLocation($object)

The $object (a text element) is located in some subsection, section or chapter. But the $object may also be an extension to a piece of documentation which is described in a super class with a location in more detail. The most detailed location for the description is returned.

Tracing

$obj->index()

Returns a string which can be used as index of headings used in this manual page.

example:

print $manual->index;

$obj->stats()

Returns a string which displays some stats about the manual.

Commonly used functions

Extends "Commonly used functions" in OODoc::Object.

$obj->filenameToPackage($filename)
OODoc::Manual->filenameToPackage($filename): Inherited, see "Commonly used functions" in OODoc::Object
$obj->mkdirhier($directory)
OODoc::Manual->mkdirhier($directory): Inherited, see "Commonly used functions" in OODoc::Object

Manual Repository

Extends "Manual Repository" in OODoc::Object.

$obj->addManual($manual): Inherited, see "Manual Repository" in OODoc::Object
$obj->mainManual($name): Inherited, see "Manual Repository" in OODoc::Object
$obj->manual($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

DIAGNOSTICS

Error: No chapter NAME in scope of package $pkg in file $source

Each documentation part requires a chapter "NAME" which starts with the manual name followed by a dash. Apparently, this was not found in the indicated file. This chapter description must be anywhere after the package statement leading the name-space.

Error: The NAME chapter does not have the right format in $source

The NAME chapter is used to figure-out what name the manual page must have. The standard format contains only one line, containing the manual's name, one dash ('-'), and then a brief explanation. For instance: =chapter NAME OODoc::Manual - one manual about a package

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().

Error: no distribution is specified for manual $name

Error: no source filename is specified for manual $name

You have to specify where you found the information for the manual. This does not need to be the name of an existing file, but usually it will be.

Error: no version is specified for manual $name

Warning: order conflict "$take" before "$insert" in $file line $number

The order of the objects in a sub-class shall be the same as that of the super class, otherwise the result of merging of the information received from both classes is undertermined.

Error: package name is not specified

You try to instantiate a manual, but have not specified the name of the package which is described in this manual, which is required.

Warning: subroutine $name location conflict: $here and $there

Finding the optimal location to list a subroutine description is a harsh job: information from various manual pages is being used.

It is not a problem to list the documentation of a certain method M in module A in chapter "METHODS", section "General", subsection "X" (which is abbreviated in the report as METHODS/General/X), and the same method M in module A::B, which extends A, in chapter "METHODS" without providing details about the section and subsection. The in most detail descripted location is used everywhere.

This warning means that the location of the method in this manual page is not related to that of the same method in an other page. For instance, in the first page it is listed in chapter "METHODS", and in the second in chapter "FUNCTIONS".

Error: two chapters named $name in $filename line $ln1 and $ln2

The indicated file contains two chapters with the same name, which is not permitted. Join the contents of both parts.

LICENSE

Copyrights 2003-2021 by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the Artistic license. See http://dev.perl.org/licenses/artistic.html

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)

NAME

INHERITANCE

SYNOPSIS

DESCRIPTION

OVERLOADED

METHODS

Constructors

Attributes

Collected

Inheritance knowledge

Processing

Tracing

Commonly used functions

Manual Repository

DIAGNOSTICS

SEE ALSO

LICENSE

Module Install Instructions