From: Brendan Byrd Date: Tue, 27 Mar 2012 01:31:45 +0000 (-0400) Subject: Utilize Pod::Inherit to add an INHERITED METHODS section to docs X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=3d4c5a8439e2c5f6b74e6c8f52117ececd9e20fa;p=dbsrgits%2FDBIx-Class-Historic.git 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 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, a user normally receives query results as instances of a +certain C, depending on the main query source. Besides being +the primary "toolset" for interaction with your data, a C also +serves to establish source metadata, which is then used during initialization +of your L instance. + +Because of these multiple seemingly conflicting purposes, it is hard to +aggregate the documentation of various methods available on a typical +C. This document serves as a general overview of C +declaration best practices, and offers an index of the available methods +(and the Components/Roles which provide them). + +=head1 AUTHOR AND CONTRIBUTORS + +See L and L 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 --- 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 --- 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 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;