/ 
OODoc-3.02
River stage zero No dependents
/ OODoc::Text::Subroutine

NAME

OODoc::Text::Subroutine - collects information about one documented sub

INHERITANCE

OODoc::Text::Subroutine
  is an OODoc::Text
  is an OODoc::Object

SYNOPSIS

DESCRIPTION

Perl has various things we can call "sub" (for "subroutine") one way or the other. This object tries to store all types of them: methods, functions, ties, and overloads. Actually, these are the most important parts of the documentation. The share more than they differ.

Extends "DESCRIPTION" in OODoc::Text.

OVERLOADED

Extends "OVERLOADED" in OODoc::Text.

overload: '""' (stringification)

Inherited, see "OVERLOADED" in OODoc::Text

overload: '==' and '!=' (numeric comparison)

Inherited, see "OVERLOADED" in OODoc::Object

overload: 'bool'

Inherited, see "OVERLOADED" in OODoc::Object

overload: 'cmp' (string comparison)

Inherited, see "OVERLOADED" in OODoc::Text

METHODS

Extends "METHODS" in OODoc::Text.

Constructors

Extends "Constructors" in OODoc::Text.

$class->new(%options)

Inherited, see "Constructors" in OODoc::Object

-Option     --Defined in     --Default
 container    OODoc::Text      <required>
 description  OODoc::Text      <empty string>
 linenr       OODoc::Text      <required>
 name         OODoc::Text      undef
 parameters                    undef
 type         OODoc::Text      <required>
container => OBJECT
description => STRING
linenr => INTEGER
name => STRING
parameters => STRING

The STRING which is found as description of the parameters which can be passed to the subroutine. Although free format, there is a convertion which you can find in the manual page of the selected parser.

type => STRING

Attributes

Extends "Attributes" in OODoc::Text.

$obj->container( [$object] )

Inherited, see "Attributes" in OODoc::Text

$obj->description()

Inherited, see "Attributes" in OODoc::Text

$obj->extends( [$object] )

Subroutine documentation can overrule the documentation on a lower level, but only when that overruled subroutine is of the same type. Improves base, see "Attributes" in OODoc::Text

$obj->linenr()

Inherited, see "Attributes" in OODoc::Text

$obj->location($manual)

Try to figure-out what the location for the subroutine is within the $manual page. Have a look at all levels of extension for this sub-routine's documentation and decides the best enclosing chapter, section and subsection. Then return that object for the current manual.

$obj->manual()

Inherited, see "Attributes" in OODoc::Text

$obj->name()

Inherited, see "Attributes" in OODoc::Text

$obj->parameters()

The parameter list for the subroutine is returned as string. The result may be undef or empty.

$obj->path()

Returns the path of the text structure which contains this subroutine.

$obj->type()

Inherited, see "Attributes" in OODoc::Text

$obj->unique()

Inherited, see "Attributes" in OODoc::Object

$obj->where()

Inherited, see "Attributes" in OODoc::Text

Manual Repository

Extends "Manual Repository" in OODoc::Text.

$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

Collected

Extends "Collected" in OODoc::Text.

$obj->addExample($object)

Inherited, see "Collected" in OODoc::Text

$obj->collectedOptions(%options)

Returns a list of option-default combinations on this subroutine.

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

In case of a $name, a default object for this method is looked up. This does not search through super classes, but solely which is defined with this subroutine. When passed an $object of type OODoc::Text::Default that will be stored.

$obj->defaults()

Returns a list of all defaults as defined by this documentation item in one manual.

$obj->diagnostic($object)

Add a new diagnostic message (a OODoc::Text::Diagnostic object) to the list already in this object. You can not look for a message because these names are without use.

$obj->diagnostics()

Returns a list of all diagnostics.

$obj->examples()

Inherited, see "Collected" in OODoc::Text

$obj->findDescriptionObject()

Inherited, see "Collected" in OODoc::Text

$obj->findOption($name)

Does a little more thorough job than option() by searching the inherited options for this subroutine as well.

$obj->openDescription()

Inherited, see "Collected" in OODoc::Text

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

In case of a $name, the option object for this method is looked up. This does not search through super classes, but solely which is defined with this subroutine. When passed an $object of type OODoc::Text::Option that will be stored.

$obj->options()

Returns a list of all options as defined by this documentation item in one manual.

DIAGNOSTICS

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 default for option $name defined in $file line $linenr

Warning: no option $name for default in $file line $linenr

Warning: subroutine $name extended by different type:

Any description of a subroutine classifies it as method, tie, overload or whatever. Apparently, this indicated subroutine is defined being of a different type on these both places, and there is an inheritance relation between these places.

In very rare cases, this warning can be ignored, but usually these situation is errorneous of confusing for the users of the library.

Warning: subroutine $name() extended by different type:\n $type1 in $file1 line $line1\n $type2 in $file2 line $line2

Warning: subroutine $name() location conflict:\n $path1 in $file1 line $line1\n $path2 in $file2 line $line2

Warning: subroutine $self location conflict: $here $super

The location of subroutine descriptions must be consistent over the manual pages. You may change the level of clearness about the exact location (place in the chapter in one page, and in a subsection in the next), as long as it is not conflicting (the subsection must be a part of the chapter).

SEE ALSO

This module is part of OODoc version 3.02, built on August 15, 2025. Website: https://perl.overmeer.net/oodoc/

LICENSE

For contributors see file ChangeLog.

This software is copyright (c) 2003-2025 by Mark Overmeer.

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