Bug #53867 for DBIx-Class-Schema-Loader: [patch] Control where table comments are displayed in POD

As discussed in #dbix-class. I wished for the POD for table level comments to be in a DESCRIPTION section instead of appended to the table name in the NAME section. Attached is a patch to make the behaviour configurable. It adds two new configuration options: pod_comment_mode and pod_comment_spillover_length. The default for pod_comment_mode maintains backward compatibility for anyone who's used this before, though personally I would be pleased if the default was simply 'description' :) Note: no test cases are included, I couldn't deciper the test system for S::L.

Index: lib/DBIx/Class/Schema/Loader.pm =================================================================== --- lib/DBIx/Class/Schema/Loader.pm (revision 8394) +++ lib/DBIx/Class/Schema/Loader.pm (working copy) @@ -488,6 +488,8 @@ kane: Jos Boumans <kane@cpan.org> +waawaamilk: Nigel McNie <nigel@mcnie.name> + ... and lots of other folks. If we forgot you, please write the current maintainer or RT. Index: lib/DBIx/Class/Schema/Loader/Base.pm =================================================================== --- lib/DBIx/Class/Schema/Loader/Base.pm (revision 8394) +++ lib/DBIx/Class/Schema/Loader/Base.pm (working copy) @@ -66,6 +66,8 @@ use_namespaces result_namespace generate_pod + pod_comment_mode + pod_comment_spillover_length /); =head1 NAME @@ -169,6 +171,25 @@ Set this to C<0> to turn off all POD generation. +=head2 pod_comment_mode + +Controls where table comments appear in the generated POD. By default table +comments are appended to the C<NAME> section of the documentation. You can +force a C<DESCRIPTION> section to be generated with the comment instead, or +choose the length threshold at which the comment is forced into the +description. + + pod_comment_mode => 'name' # default behaviour + pod_comment_mode => 'description' # force creation of DESCRIPTION section + pod_comment_mode => 'auto' # use description if length > pod_comment_spillover_length + +=head2 pod_comment_spillover_length + +When pod_comment_mode is set to C<auto>, this is the length of the comment at +which it will be forced into a separate description section. + +The default is C<60> + =head2 relationship_attrs Hashref of attributes to pass to each generated relationship, listed @@ -431,6 +452,8 @@ $self->use_namespaces(1) unless defined $self->use_namespaces; $self->generate_pod(1) unless defined $self->generate_pod; + $self->pod_comment_mode('name') unless defined $self->pod_comment_mode; + $self->pod_comment_spillover_length(60) unless defined $self->pod_comment_spillover_length; $self; } @@ -1395,14 +1418,23 @@ if ( $method eq 'table' ) { my ($table) = @_; + my $pcm = $self->pod_comment_mode; + my ($comment, $comment_overflows, $comment_in_name, $comment_in_desc); + if ( $self->can('_table_comment') ) { + $comment = $self->_table_comment($table); + $comment_overflows = ($comment and length $comment > $self->pod_comment_spillover_length); + $comment_in_name = ($pcm eq 'name' or ($pcm eq 'auto' and !$comment_overflows)); + $comment_in_desc = ($pcm eq 'description' or ($pcm eq 'auto' and $comment_overflows)); + } $self->_pod( $class, "=head1 NAME" ); my $table_descr = $class; - if ( $self->can('_table_comment') ) { - my $comment = $self->_table_comment($table); - $table_descr .= " - " . $comment if $comment; - } + $table_descr .= " - " . $comment if $comment and $comment_in_name; $self->{_class2table}{ $class } = $table; $self->_pod( $class, $table_descr ); + if ($comment and $comment_in_desc) { + $self->_pod( $class, "=head1 DESCRIPTION" ); + $self->_pod( $class, $comment ); + } $self->_pod_cut( $class ); } elsif ( $method eq 'add_columns' ) { $self->_pod( $class, "=head1 ACCESSORS" ); Index: Changes =================================================================== --- Changes (revision 8394) +++ Changes (working copy) @@ -1,6 +1,8 @@ Revision history for Perl extension DBIx::Class::Schema::Loader - added 'generate_pod' option, defaults to on + - added 'pod_comment_mode' and 'pod_comment_spillover_length' to + control table comment generation (waawaamilk) 0.04999_14 2010-01-14 06:47:07 - use_namespaces now default, with upgrade/downgrade support