=encoding utf8

=head1 NAME

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

=head1 INHERITANCE

 OODoc::Text::Subroutine
   is an OODoc::Text
   is an 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, functions, ties, and overloads.  Actually, these are the
most important parts of the documentation.  The share more than
they differ.

Extends L<"DESCRIPTION" in OODoc::Text|OODoc::Text/"DESCRIPTION">.

=head1 OVERLOADED

Extends L<"OVERLOADED" in OODoc::Text|OODoc::Text/"OVERLOADED">.

=over 4

=item overload: B<'""' (stringification)>

Inherited, see L<OODoc::Text/"OVERLOADED">

=item overload: B<'==' and '!=' (numeric comparison)>

Inherited, see L<OODoc::Object/"OVERLOADED">

=item overload: B<'bool'>

Inherited, see L<OODoc::Object/"OVERLOADED">

=item overload: B<'cmp' (string comparison)>

Inherited, see L<OODoc::Text/"OVERLOADED">

=back

=head1 METHODS

Extends L<"METHODS" in OODoc::Text|OODoc::Text/"METHODS">.

=head2 Constructors

Extends L<"Constructors" in OODoc::Text|OODoc::Text/"Constructors">.

=over 4

=item $class-E<gt>B<new>(%options)

Inherited, see L<OODoc::Object/"Constructors">

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

=over 2

=item container => OBJECT

=item description => STRING

=item linenr => INTEGER

=item name => STRING

=item 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.

=item type => STRING

=back

=back

=head2 Attributes

Extends L<"Attributes" in OODoc::Text|OODoc::Text/"Attributes">.

=over 4

=item $obj-E<gt>B<container>( [$object] )

Inherited, see L<OODoc::Text/"Attributes">

=item $obj-E<gt>B<description>()

Inherited, see L<OODoc::Text/"Attributes">

=item $obj-E<gt>B<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 L<OODoc::Text/"Attributes">

=item $obj-E<gt>B<linenr>()

Inherited, see L<OODoc::Text/"Attributes">

=item $obj-E<gt>B<location>($manual)

Try to figure-out what the location for the subroutine is within the
C<$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.

=item $obj-E<gt>B<manual>()

Inherited, see L<OODoc::Text/"Attributes">

=item $obj-E<gt>B<name>()

Inherited, see L<OODoc::Text/"Attributes">

=item $obj-E<gt>B<parameters>()

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

=item $obj-E<gt>B<path>()

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

=item $obj-E<gt>B<type>()

Inherited, see L<OODoc::Text/"Attributes">

=item $obj-E<gt>B<unique>()

Inherited, see L<OODoc::Object/"Attributes">

=item $obj-E<gt>B<where>()

Inherited, see L<OODoc::Text/"Attributes">

=back

=head2 Manual Repository

Extends L<"Manual Repository" in OODoc::Text|OODoc::Text/"Manual Repository">.

=over 4

=item $obj-E<gt>B<addManual>($manual)

Inherited, see L<OODoc::Object/"Manual Repository">

=item $obj-E<gt>B<findManual>($name)

Inherited, see L<OODoc::Object/"Manual Repository">

=item $obj-E<gt>B<mainManual>($name)

Inherited, see L<OODoc::Object/"Manual Repository">

=item $obj-E<gt>B<manuals>()

Inherited, see L<OODoc::Object/"Manual Repository">

=item $obj-E<gt>B<manualsForPackage>($name)

Inherited, see L<OODoc::Object/"Manual Repository">

=item $obj-E<gt>B<packageNames>()

Inherited, see L<OODoc::Object/"Manual Repository">

=item $obj-E<gt>B<publicationIndex>()

Inherited, see L<OODoc::Object/"Manual Repository">

=item $obj-E<gt>B<publish>(\%options)

Inherited, see L<OODoc::Object/"Manual Repository">

=back

=head2 Collected

Extends L<"Collected" in OODoc::Text|OODoc::Text/"Collected">.

=over 4

=item $obj-E<gt>B<addExample>($object)

Inherited, see L<OODoc::Text/"Collected">

=item $obj-E<gt>B<collectedOptions>(%options)

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

=item $obj-E<gt>B<default>($name|$object)

In case of a C<$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 C<$object> of type L<OODoc::Text::Default|OODoc::Text::Default>
that will be stored.

=item $obj-E<gt>B<defaults>()

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

=item $obj-E<gt>B<diagnostic>($object)

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

=item $obj-E<gt>B<diagnostics>()

Returns a list of all diagnostics.

=item $obj-E<gt>B<examples>()

Inherited, see L<OODoc::Text/"Collected">

=item $obj-E<gt>B<findDescriptionObject>()

Inherited, see L<OODoc::Text/"Collected">

=item $obj-E<gt>B<findOption>($name)

Does a little more thorough job than L<option()|OODoc::Text::Subroutine/"Collected"> by searching the inherited
options for this subroutine as well.

=item $obj-E<gt>B<openDescription>()

Inherited, see L<OODoc::Text/"Collected">

=item $obj-E<gt>B<option>($name|$object)

In case of a C<$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 C<$object> of type L<OODoc::Text::Option|OODoc::Text::Option>
that will be stored.

=item $obj-E<gt>B<options>()

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

=back

=head1 DIAGNOSTICS

=over 4

=item Error: manual definition requires manual object

A call to L<addManual()|OODoc::Object/"Manual Repository"> 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 Repository"> or L<mainManual()|OODoc::Object/"Manual Repository">.

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

Z<>

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

Z<>

=item 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.

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

Z<>

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

Z<>

=item 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).

=back

=head1 SEE ALSO

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

=head1 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.

