update pod_comment_mode POD

[dbsrgits/DBIx-Class-Schema-Loader.git] / lib / DBIx / Class / Schema / Loader / Base.pm

diff --git a/lib/DBIx/Class/Schema/Loader/Base.pm b/lib/DBIx/Class/Schema/Loader/Base.pm
index eb8902b..39431fa 100644 (file)
--- a/lib/DBIx/Class/Schema/Loader/Base.pm
+++ b/lib/DBIx/Class/Schema/Loader/Base.pm
@@ -16,7 +16,7 @@ use File::Temp qw//;
 use Class::Unload;
 require DBIx::Class;
 
-our $VERSION = '0.04999_13';
+our $VERSION = '0.04999_14';
 
 __PACKAGE__->mk_group_ro_accessors('simple', qw/
                                 schema
@@ -65,6 +65,9 @@ __PACKAGE__->mk_group_accessors('simple', qw/
                                 _rewriting_result_namespace
                                 use_namespaces
                                 result_namespace
+                                generate_pod
+                                pod_comment_mode
+                                pod_comment_spillover_length
 /);
 
 =head1 NAME
@@ -158,6 +161,48 @@ next major version upgrade:
 
     __PACKAGE__->naming('v5');
 
+=head2 generate_pod
+
+By default POD will be generated for columns and relationships, using database
+metadata for the text if available and supported.
+
+Reading database metadata (e.g. C<COMMENT ON TABLE some_table ...>) is only
+supported for Postgres right now.
+
+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.
+
+=over 4
+
+=item name
+
+Use C<NAME> section only.
+
+=item description
+
+Force C<DESCRIPTION> always.
+
+=item auto
+
+Use C<DESCRIPTION> if length > L</pod_comment_spillover_length>, this is the
+default.
+
+=back
+
+=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
@@ -419,6 +464,9 @@ sub new {
     $self->_check_back_compat;
 
     $self->use_namespaces(1) unless defined $self->use_namespaces;
+    $self->generate_pod(1)   unless defined $self->generate_pod;
+    $self->pod_comment_mode('auto')         unless defined $self->pod_comment_mode;
+    $self->pod_comment_spillover_length(60) unless defined $self->pod_comment_spillover_length;
 
     $self;
 }
@@ -1361,7 +1409,7 @@ sub _dbic_stmt {
     my $method = shift;
 
     # generate the pod for this statement, storing it with $self->_pod
-    $self->_make_pod( $class, $method, @_ );
+    $self->_make_pod( $class, $method, @_ ) if $self->generate_pod;
 
     my $args = dump(@_);
     $args = '(' . $args . ')' if @_ < 2;
@@ -1381,14 +1429,23 @@ sub _make_pod {
 
     if ( $method eq 'table' ) {
         my ($table) = @_;
-        $self->_pod( $class, "=head1 NAME" );
-        my $table_descr = $class;
+        my $pcm = $self->pod_comment_mode;
+        my ($comment, $comment_overflows, $comment_in_name, $comment_in_desc);
         if ( $self->can('_table_comment') ) {
-            my $comment = $self->_table_comment($table);
-            $table_descr .= " - " . $comment if $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;
+        $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" );
@@ -1437,7 +1494,6 @@ sub _pod_cut {
     $self->_raw_stmt( $class, "\n=cut\n" );
 }
 
-
 # Store a raw source line for a class (for dumping purposes)
 sub _raw_stmt {
     my ($self, $class, $stmt) = @_;