Utilize Pod::Inherit to add an INHERITED METHODS section to docs

diff --git a/lib/DBIx/Class/Manual/ResultClass.pod b/lib/DBIx/Class/Manual/ResultClass.pod
new file mode 100644 (file)
index 0000000..7699a81
--- /dev/null
+++ b/lib/DBIx/Class/Manual/ResultClass.pod
@@ -0,0 +1,56 @@
+
+=head1 NAME
+
+DBIx::Class::Manual::ResultClass - Representing a single result (row) from
+a DB query
+
+=head1 SYNOPSIS
+
+  package My::Schema::Result::Track;
+
+  use parent 'DBIx::Class::Core';
+
+  __PACKAGE__->table('tracks');
+
+  __PACKAGE__->add_columns({
+    id => {
+      data_type => 'int',
+      is_auto_increment => 1,
+    },
+    cd_id => {
+      data_type => 'int',
+    },
+    title => {
+      data_type => 'varchar',
+      size => 50,
+    },
+    rank => {
+      data_type => 'int',
+      is_nullable => 1,
+    },
+  });
+
+  __PACKAGE__->set_primary_key('id');
+  __PACKAGE__->add_unique_constraint(u_title => ['cd_id', 'title']);
+
+=head1 DESCRIPTION
+
+In L<DBIx::Class>, a user normally receives query results as instances of a
+certain C<Result Class>, depending on the main query source.  Besides being
+the primary "toolset" for interaction with your data, a C<Result Class> also
+serves to establish source metadata, which is then used during initialization
+of your L<DBIx::Class::Schema> instance.
+
+Because of these multiple seemingly conflicting purposes, it is hard to
+aggregate the documentation of various methods available on a typical
+C<Result Class>. This document serves as a general overview of C<Result Class>
+declaration best practices, and offers an index of the available methods
+(and the Components/Roles which provide them).
+
+=head1 AUTHOR AND CONTRIBUTORS
+
+See L<AUTHOR|DBIx::Class/AUTHOR> and L<CONTRIBUTORS|DBIx::Class/CONTRIBUTORS> in DBIx::Class
+
+=head1 LICENSE
+
+You may distribute this code under the same terms as Perl itself.

diff --git a/lib/DBIx/Class/Optional/Dependencies.pm b/lib/DBIx/Class/Optional/Dependencies.pm
index b35c3c9..281d30a 100644 (file)
--- a/lib/DBIx/Class/Optional/Dependencies.pm
+++ b/lib/DBIx/Class/Optional/Dependencies.pm
@@ -107,7 +107,10 @@ my $rdbms_firebird_odbc = {
 
 my $reqs = {
   dist => {
-    #'Module::Install::Pod::Inherit' => '0.01',
+    req => {
+      'Pod::Inherit' => '0.16',
+      'Pod::Tree'    => '0',
+  },
   },
 
   replicated => {
@@ -713,7 +716,7 @@ sub _gen_pod {
 "\n\n---------------------------------------------------------------------\n"
   ;
 
-  # do not ask for a recet version, use 1.x API calls
+  # do not ask for a recent version, use 1.x API calls
   # this *may* execute on a smoker with old perl or whatnot
   require File::Path;
 

diff --git a/maint/Makefile.PL.inc/54_autogen_inherited_pod.pl b/maint/Makefile.PL.inc/54_autogen_inherited_pod.pl
index 6b0e3c8..9dfa71d 100644 (file)
--- a/maint/Makefile.PL.inc/54_autogen_inherited_pod.pl
+++ b/maint/Makefile.PL.inc/54_autogen_inherited_pod.pl
@@ -1,6 +1,19 @@
-# FIXME Disabled due to unsolved issues, ask theorbtwo
-#require Module::Install::Pod::Inherit;
-#PodInherit();
+# generate the inherit pods as both a clone-dir step, and a makefile distdir step
+
+print "Regenerating project documentation to include inherited methods\n";
+# if the author doesn't have them, don't fail the initial "perl Makefile.pl" step
+do "maint/gen_pod_inherit" or print "\n!!! FAILED: $@\n";
+
+postamble <<"EOP";
+
+.PHONY: dbic_clonedir_gen_inherit_pods
+
+create_distdir : dbic_clonedir_gen_inherit_pods
+
+dbic_clonedir_gen_inherit_pods :
+\t\$(ABSPERL) maint/gen_pod_inherit
+
+EOP
 
 # keep the Makefile.PL eval happy
 1;

diff --git a/maint/gen_pod_inherit b/maint/gen_pod_inherit
new file mode 100755 (executable)
index 0000000..b7adc14
--- /dev/null
+++ b/maint/gen_pod_inherit
@@ -0,0 +1,64 @@
+#!/usr/bin/env perl
+
+use warnings;
+use strict;
+
+my $lib_dir = 'lib';
+my $pod_dir = '.generated_pod';
+
+die "POD generator must be executed from the dist root\n"
+  unless -d $lib_dir and -d $pod_dir;
+
+require Pod::Inherit;
+
+Pod::Inherit->new({
+   input_files       => $lib_dir,
+   out_dir           => $pod_dir,
+   force_permissions => 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",
+   },
+   # skip the deprecated classes that give out *DEPRECATED* warnings
+   skip_classes      => [ qw(
+      lib/DBIx/Class/Storage/DBI/Sybase/MSSQL.pm
+      lib/DBIx/Class/Serialize/Storable.pm
+      lib/DBIx/Class/ResultSetManager.pm
+      lib/DBIx/Class/InflateColumn/File.pm
+      lib/DBIx/Class/DB.pm
+      lib/DBIx/Class/CDBICompat/
+      lib/DBIx/Class/CDBICompat.pm
+   ),
+   # skip the ::Storage:: family for now
+   qw(
+      lib/DBIx/Class/Storage/
+      lib/DBIx/Class/Storage.pm
+   ),
+      'lib/DBIx/Class/Storage/DBI/Replicated/Pool.pm',  # this one just errors out with: The 'add_attribute' method cannot be called on an immutable instance
+      'lib/DBIx/Class/Relationship.pm',                 # it already documents its own inheritors
+      'lib/DBIx/Class/Core.pm',                         # we actually don't want this populated in favor of redirecting users to the ResultClass docs
+      'lib/DBIx/Class/Optional/Dependencies.pm'         # the POD is already auto-generated
+   ],
+   # these appear everywhere, and are typically lower-level methods not used by the general user
+   skip_inherits     => [ qw/
+      DBIx::Class
+      DBIx::Class::Componentised
+      Class::C3::Componentised
+      DBIx::Class::AccessorGroup
+      Class::Accessor::Grouped
+      Moose::Object
+      Exporter
+   / ],
+   force_inherits    => {
+      'DBIx::Class::Manual::ResultClass' => 'DBIx::Class::Core',  # this forces the contents of ::Core to be dumped into the POD doc for ::ResultClass
+   },
+   dead_links        => '',
+   method_format     => 'L<%m|%c/%m>',
+   #debug => 1,
+})->write_pod;
+
+# important - write_pod returns undef >.<
+1;