upload 0.05001

[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 6ee29e3..d915653 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_14';
+our $VERSION = '0.05001';
 
 __PACKAGE__->mk_group_ro_accessors('simple', qw/
                                 schema
@@ -66,6 +66,8 @@ __PACKAGE__->mk_group_accessors('simple', qw/
                                 use_namespaces
                                 result_namespace
                                 generate_pod
+                                pod_comment_mode
+                                pod_comment_spillover_length
 /);
 
 =head1 NAME
@@ -169,6 +171,38 @@ 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. Smaller table
+comments are appended to the C<NAME> section of the documentation, and larger
+ones are inserted into C<DESCRIPTION> instead. You can force a C<DESCRIPTION>
+section to be generated with the comment always, only use C<NAME>, 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
@@ -431,6 +465,8 @@ sub new {
 
     $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;
 }
@@ -566,8 +602,9 @@ sub _find_file_in_inc {
     foreach my $prefix (@INC) {
         my $fullpath = File::Spec->catfile($prefix, $file);
         return $fullpath if -f $fullpath
-            and Cwd::abs_path($fullpath) ne
-               (Cwd::abs_path(File::Spec->catfile($self->dump_directory, $file)) || '');
+            # abs_path throws on Windows for nonexistant files
+            and eval { Cwd::abs_path($fullpath) } ne
+               (eval { Cwd::abs_path(File::Spec->catfile($self->dump_directory, $file)) } || '');
     }
 
     return;
@@ -1373,7 +1410,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;
@@ -1391,18 +1428,25 @@ sub _make_pod {
     my $class  = shift;
     my $method = shift;
 
-    return unless $self->generate_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" );