_rewriting_result_namespace
use_namespaces
result_namespace
+ generate_pod
+ pod_comment_mode
+ pod_comment_spillover_length
/);
=head1 NAME
__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. 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
$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;
}
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;
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;
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" );
$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) = @_;