[jifty-devel] doc diff for Jifty::DBI::Schema

Chris Fedde chris at fedde.littleton.co.us
Thu Feb 2 11:20:54 EST 2006


Below are diffs adding a partially filled out pod to Jifty::DBI::Schema.
Please provide any feedback and I'll update and re-post
--
    Chris Fedde
--
Index: lib/Jifty/DBI/Schema.pm
===================================================================
--- lib/Jifty/DBI/Schema.pm	(revision 537)
+++ lib/Jifty/DBI/Schema.pm	(working copy)
@@ -3,6 +3,49 @@
 
 package Jifty::DBI::Schema;
 
+=head1 NAME
+
+Jifty::DBI::Schema - Use a simple syntax to describe a Jifty table.
+
+=head1 VERSION
+
+Version 0.03
+
+=cut
+
+our $VERSION = '$LastChangedRevision$' =~ /(\d+)/ ? $1 : 0;
+
+=head1 SYNOPSIS
+
+package Wifty::Model::Page::Schema;
+use Jifty::DBI::Schema;
+
+
+=cut
+
+=head1 DESCRIPTION
+
+Each Jifty Application::Model::Class module describes a collection class
+for for a Jifty application.  Each column statement sets out the name and
+attributes used to describe the column in a backend database, html form
+and other processing.  For example:
+
+    column content =>
+	type is 'text',
+	label is 'Content',
+	render_as 'textarea';
+
+defines a column called "content" that is of type "text".  It will be
+rendered with the label "Content" (note the capital) and as a "textarea" in
+a HTML form.
+
+Jifty::DBI::Schema builds a Jifty::DBI::Column.  That class defines other
+attributes for database structure that are not exposed directly here.
+One example of this is the  "refers_to" method used to create associations
+between classes.
+
+=cut
+
 use Carp qw/carp/;
 use Exporter::Lite;
 our @EXPORT
@@ -10,6 +53,17 @@
 
 our $SCHEMA;
 
+=head1 FUNCTIONS
+
+All these functions are exported.
+
+=head2 column
+
+Set forth the description of a column in the data store.
+If the name ends with '_id' then it is taken to be a "primary key".
+
+=cut
+
 sub column {
     my $name = lc(shift);
 
@@ -59,84 +113,177 @@
     $from->COLUMNS->{$name} = $column;
 }
 
+=head2 type
+
+type passed to our database abstraction layer, which should resolve it to
+a database-specific type.
+
+=cut
+
 sub type ($) {
     _list( type => shift );
 }
 
+=head2 default
+
+Give a default value for the column.
+
+=cut
+
 sub default ($) {
     _list( default => shift );
 }
 
+=head2 validator
+
+=cut
+
 sub validator ($) {
     _list( validator => shift );
 }
 
+=head2 immutable
+
+=cut
+
 sub immutable () {
     _item( [ writable => 0 ] );
 }
 
+=head2 unreadable
+
+=cut
+
 sub unreadable {
     _item( [ readable => 0 ] );
 }
 
+=head2 length
+
+=cut
+
 sub length ($) {
     _list( length => shift );
 }
 
+=head2 mandatory
+
+Mark as a required.  May be used for generating ddl and for UI behaviors.
+
+=cut
+
 sub mandatory () {
     _item( [ mandatory => 1 ] );
 }
 
+=head2 distinct
+
+=cut
+
 sub distinct () {
     _item( [ distinct => 1 ] );
 }
 
+=head2 not_null
+
+used by the database abstraction to generate a constraint.
+
+=cut
+
 sub not_null () {
     carp "'is not_null' is deprecated in favor of 'is mandatory'";
     _item( [ mandatory => 1 ] );
 }
 
+=head2 input_filters
+
+=cut
+
 sub input_filters ($) {
     _list( input_filters => shift );
 }
 
+=head2 output_filters
+
+=cut
+
 sub output_filters ($) {
     _list( output_filters => shift );
 }
 
+=head2 since
+
+what Application version this column was last changed
+
+=cut
+
 sub since ($) {
     _list( since => shift );
 }
 
+=head2 valid_values
+
+=cut
+
 sub valid_values ($) {
     _list( valid_values => shift );
 }
 
+=head2 label
+
+=cut
+
 sub label ($) {
     _list( label => shift );
 }
 
+=head2 hints
+
+=cut
+
 sub hints ($) {
     _list( hints => shift );
 }
 
+=head2 render_as
+
+Used in html generation to pick an field type.
+
+=cut
+
 sub render_as ($) {
     _list( render_as => shift );
 }
 
+=head2 is
+
+=cut
+
 sub is ($) {
     my $thing = shift;
     ref $thing eq "ARRAY" ? _list( @{$thing} ) : _item($thing);
 }
 
+=head2 by
+
+=cut
+
 sub by ($) {
     _list( by => shift );
 }
 
+=head2 are
+
+=cut
+
 sub are (@) {
     _item( [@_] );
 }
 
+=head2 on
+
+=cut
+
 sub on ($) {
     _list( self => shift );
 }
@@ -158,4 +305,19 @@
     $_[0];
 }
 
+=head1 EXAMPLE
+
+=head1 AUTHOR
+
+=head1 BUGS
+
+=head1 SUPPORT
+
+=head1 COPYRIGHT & LICENSE
+
+This program is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+
+=cut
+
 1;


More information about the jifty-devel mailing list