NAME

Pod::Inherit - auto-create POD sections listing inherited methods

SYNOPSIS

  use Pod::Inherit;

  my $config = {
    out_dir          => "/usr/src/perl/dbix-class/bast/DBIx-Class/0.08/trunk/doc",
    input_files      => ['/usr/src/perl/dbix-class/bast/DBIx-Class/0.08/trunk/lib/'],
    skip_underscored => 1,
    class_map        => {
      'DBIx::Class::Relationship::HasMany'    => 'DBIx::Class::Relationship',
      'DBIx::Class::Relationship::HasOne'     => 'DBIx::Class::Relationship',
      'DBIx::Class::Relationship::BelongsTo'  => 'DBIx::Class::Relationship',
      'DBIx::Class::Relationship::ManyToMany' => 'DBIx::Class::Relationship',
      'DBIx::Class::ResultSourceProxy'        => 'DBIx::Class::ResultSource',
      'DBIx::Class::ResultSourceProxy::Table' => 'DBIx::Class::ResultSource',
    },
    skip_classes    => [
      'lib/DBIx/Class/Serialize/Storable.pm',
      'DBIx::Class::Serialize::Storable',
    ],
    skip_inherits   => [ qw/
      DBIx::Class::Componentised
      Class::C3::Componentised
    / ],
    force_inherits  => {
      'lib/DBIx/Class/ResultClass.pod' => 'DBIx::Class::Core',
      'DBIx::Class::AccessorGroup' => [
        'Class::Accessor',
        'Class::Accessor::Grouped'
      ]
    },
    method_format   => 'L<%m|%c/%m>',
    dead_links      => '',
    debug           => 1,
  };

  my $pi = Pod::Inherit->new( $config });
  $pi->write_pod;

DESCRIPTION

Ever written a module distribution with base classes and dependencies, that had the POD for the various methods next to them, but hard to find for the user of your modules? Ever wished POD could be inheritable? Now it can.

This module will load each of the classes in the list of input files or directories given (default: @ARGV), auto-discover which methods each class provides, locate the actual class the method is defined in, and produce a list in POD.

The resulting documentation is written out to a separate .pod file for each class (.pm) encountered. The new file contains the original POD from the Perl Module file, plus a section called INHERITED METHODS. The new section lists each class that the current class inherits from, plus each method that can be used in the current class as a result.

By default, methods beginning with an underscore, _ are skipped, as by convention these are private methods.

METHODS

new

Arguments: \%config

Return Value: Pod::Inherit object

Create a new Pod::Inherit object.

\%config

The config hashref can contain the following keys:

skip_underscored

Input: boolean

Default: true

Do not display inherited methods that begin with an underscore. Set to 0 to display these as well.

input_files

Input: [ @directories ] | $directory

Default: [ @ARGV ]

Arrayref of directories to search for .pm files in, or a list of .pm files or a mixture.

out_dir

Input: $directory

Default: Same as input_files

A directory to output the results into. If not supplied, the .pod file is created alongside the .pm file it came from.

force_permissions

Input: boolean

Default: false

ExtUtils::MakeMaker makes directories in blib read-only before we'd like to write into them. If this is set to a true value, we'll catch permission denied errors, and try to make the directory writeable, write the file, and then set it back to how it was before.

class_map

Input: { $class_only => $class_only, ... }

Default: none

The keys represent classes in which inherited methods will be found; the values are the classes which it should link to in the new POD for the actual POD of the methods.

Some distributions will already have noticed the plight of the users, and documented the methods of some of their base classes further up the inheritance chain. This config option lets you tell Pod::Inherit where you moved the POD to.

skip_classes

Input: [ @class_or_pm_files ] | $class_or_pm_file

Default: none

Any class/file found in the list will be skipped for POD creation.

skip_inherits

Input: [ @classes_only ] | $classes_only

Default: none

This is a list of classes that shouldn't show up in any of the INHERITED METHODS sections. Good candidates include:

  Class::C3::Componentised
  Any other *::Componentised
  Class::Accessor::Grouped
  Moose::Object or most Moose stuff
  Exporter

force_inherits

Input: { $class_or_pmpod_file => $class_only | [ @classes_only ], ... }

Default: none

A hashref of arrayrefs. Like the opposite of skip_inherits, this will forcefully add the classes listed to the INHERITED METHODS sections, except this will only work on a per-class basis. The keys represent the classes affected; the values are arrayrefs (or single strings) specifying which classes to add.

In order to access the methods for the new modules, we'll need to load them manually after the main class is loaded. If there are some sort of weird conflicts, this may cause undesirable results. Also, any methods that the NEW module inherits will also be added to the method list.

You can also use this option to add a INHERITED METHODS to a separate POD file. Note that this is the only case where a POD would get loaded and read, since it really can't work otherwise. Also, be sure to specify a different output directory, else you will likely overwrite your existing POD.

method_format

Input: $format_string

Default: '%m'

A string with a few custom percent-encoded variables. This string will be used on each method name found when writing the new POD section. The custom variables are:

  %m = method name
  %c = class name
  %% = literal percent sign

Thus, the default just prints out the method name, unaltered.

This string can be used to add method links to the POD files (like 'L<%m|%c/%m'>), or to change the formatting (like 'C<%m'>).

dead_links

Input: $format_string

Default: undef

A string with the same format as method_format. This is the string used for methods that don't exist in the inherited module's documentation. A blank string ('') will remove any dead links. The default is to not check for dead links.

This option typically only makes sense if method_format is a link, but it can be used to automatically remove undocumented methods or present them in a different manner.

This feature requires Pod::Tree to be installed.

debug

Input: 0|1|2

Default: 0

A debug level of 1 will print out a managable level of debug information per module. To get POD outputs, set this to 2.

This used to be set with $Pod::Inherit::DEBUG, but this property is now preferred. However, the old method still works for backwards-compatibility.

write_pod

Arguments: none

Return Value: none

Run the pod creation stage.

create_pod

Arguments: $src, $root_dir?

Return Value: $pod_text | undef

Creates a POD file. Actually, this just outputs the text of the resulting file, so it's up to you to write this somewhere. If the POD wouldn't produce a INHERITED METHODS, this will return undef.

Strange situations, such as non-existant files, do/require problems, etc. will warn and return undef as well.

The optional $root_dir would basically be whatever lib/blib directory is in the $src, used mainly for POD->Class conversion. That part of the directory would still need to be on $src.

Inline configuration

As well as passing explicit configuration options to "new", you can also leave Pod::Inherit hints in your actual code. To define in a class that all methods with a leading underscore should be included when listing methods in that module, use the following snippet in your code:

  our %_pod_inherit_config = ( skip_underscored => 0 );

AUTHOR

James Mastros, theorbtwo <james@mastros.biz>

CONTRIBUTORS

Brendan Byrd, SineSwiper <BBYRD@cpan.org>

LICENSE

You may distribute this code under the same terms as Perl itself.

cpanm Pod::Inherit

perl -MCPAN -e shell
install Pod::Inherit