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


  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    => [
    skip_inherits   => [ qw/
    / ],
    force_inherits  => {
      'lib/DBIx/Class/ResultClass.pod' => 'DBIx::Class::Core',
      'DBIx::Class::AccessorGroup' => [
    method_format   => 'L<%m|%c/%m>',
    dead_links      => '',
    debug           => 1,

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


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.



Arguments: \%config
Return Value: Pod::Inherit object

Create a new Pod::Inherit object.


The config hashref can contain the following keys:


Input: boolean
Default: true

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


Input: [ @directories ] | $directory
Default: [ @ARGV ]

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


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.


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.


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.


Input: [ @class_or_pm_files ] | $class_or_pm_file
Default: none

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


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:

  Any other *::Componentised
  Moose::Object or most Moose stuff


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.


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

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.


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.


Arguments: none
Return Value: 1 on success

Run the pod creation stage.


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


James Mastros, theorbtwo <>


Brendan Byrd, SineSwiper <>


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