
=head1 NAME

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


=head1 INHERITANCE

 OODoc::Text::Subroutine
   is a OODoc::Text
   is a OODoc::Object


=head1 SYNOPSIS



=head1 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, funtion, ties, and overloads. Actually, these are the
most important parts of the documentation.  The share more than
they differ.



=head1 METHODS


=head2 Attributes


$obj-E<gt>B<parameters>

=over 4

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

=back

=head2 Collected


$obj-E<gt>B<default>(NAME|OBJECT)

=over 4

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.

=back

$obj-E<gt>B<defaults>

=over 4

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

=back

$obj-E<gt>B<diagnostic>(OBJECT)

=over 4

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.

=back

$obj-E<gt>B<diagnostics>

=over 4

Returns a list of all diagnostics.

=back

$obj-E<gt>B<findOption>(NAME)

=over 4

Does a little more thorrow job than L<option()|"Collected"> bu searching the inherited
options for this subroutine as well.

=back

$obj-E<gt>B<option>(NAME|OBJECT)

=over 4

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.

=back

$obj-E<gt>B<options>

=over 4

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

=back

=head2 Container


$obj-E<gt>B<container>

=over 4

See L<OODoc::Text/"Container">

=back

$obj-E<gt>B<manual>

=over 4

See L<OODoc::Text/"Container">

=back

=head2 Examples


$obj-E<gt>B<example>(OBJECT)

=over 4

See L<OODoc::Text/"Examples">

=back

$obj-E<gt>B<examples>

=over 4

See L<OODoc::Text/"Examples">

=back

=head2 Initiation


OODoc::Text::Subroutine-E<gt>B<new>(OPTIONS)

=over 4

See L<OODoc::Text::Diagnostic/"METHODS">

=back

=head2 Inheritance


$obj-E<gt>B<collectedOptions>

=over 4

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

=back

$obj-E<gt>B<location>(MANUAL)

=over 4

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.

=back

=head2 Commonly used functions


$obj-E<gt>B<filenameToPackage>(FILENAME)

OODoc::Text::Subroutine-E<gt>B<filenameToPackage>(FILENAME)

=over 4

See L<OODoc::Object/"Commonly used functions">

=back

$obj-E<gt>B<mergeObjects>(OPTIONS)

=over 4

See L<OODoc::Object/"Commonly used functions">

=back

$obj-E<gt>B<mkdirhier>(DIRECTORY)

OODoc::Text::Subroutine-E<gt>B<mkdirhier>(DIRECTORY)

=over 4

See L<OODoc::Object/"Commonly used functions">

=back

$obj-E<gt>B<unique>

=over 4

See L<OODoc::Text/"METHODS">

=back

=head2 Manual database

All manuals can be reached everywhere in the program: it is a global
collection.

$obj-E<gt>B<addManual>(MANUAL)

=over 4

See L<OODoc::Object/"Manual database">

=back

$obj-E<gt>B<mainManual>(NAME)

=over 4

See L<OODoc::Object/"Manual database">

=back

$obj-E<gt>B<manuals>

=over 4

See L<OODoc::Object/"Manual database">

=back

$obj-E<gt>B<manualsForPackage>(NAME)

=over 4

See L<OODoc::Object/"Manual database">

=back

$obj-E<gt>B<packageNames>

=over 4

See L<OODoc::Object/"Manual database">

=back



=head1 DIAGNOSTICS

I<Error:> manual definition requires manual object

A call to L<addManual()|OODoc::Object/"Manual database"> expects a new manual object (a L<OODoc::Manual|OODoc::Manual>),
however an incompatible thing was passed.  Usually, intended was a call
to L<manualsForPackage()|OODoc::Object/"Manual database"> or L<mainManual()|OODoc::Object/"Manual database">.

I<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.

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






=head1 REFERENCES

See the OODoc website at L<$website> for more details.

=head1 COPYRIGHTS

Module version $version.
Written by Mark Overmeer (mark@overmeer.net).  See the ChangeLog for
other contributors.

Copyright (c) 2001-2002 by the authors. All rights reserved.  This program
is free software; you can redistribute it and/or modify it under the
same terms as Perl itself.


