some documentation improvements, some test fixes

[maypole.git] / lib / Maypole / Model / CDBI.pm

diff --git a/lib/Maypole/Model/CDBI.pm b/lib/Maypole/Model/CDBI.pm
index 4423b69b63e2b5b2fad74158312b1d86e87da65b..5013d4ff54063f9d07f4617f5336f0f3d157cd89 100644 (file)
--- a/lib/Maypole/Model/CDBI.pm
+++ b/lib/Maypole/Model/CDBI.pm
@@ -16,6 +16,11 @@ It implements a base set of methods required for a Maypole Data Model.
 
 It inherits accessor and helper methods from L<Maypole::Model::Base>.
 
+When specified as the application model, it will use Class::DBI::Loader
+to generate the model classes from the provided database. If you do not
+wish to use this functionality, use L<Maypole::Model::CDBI::Plain> which
+will instead use Class::DBI classes provided.
+
 =cut
 
 use base qw(Maypole::Model::Base Class::DBI);
@@ -38,7 +43,7 @@ use attributes ();
 
 Action methods are methods that are accessed through web (or other public) interface.
 
-=item do_edit
+=head2 do_edit
 
 If there is an object in C<$r-E<gt>objects>, then it should be edited
 with the parameters in C<$r-E<gt>params>; otherwise, a new object should
@@ -441,6 +446,9 @@ sub accessor_classes {
 
 =head2 stringify_column
 
+   Returns the name of the column to use when stringifying
+   and object.
+
 =cut
 
 sub stringify_column {
@@ -455,6 +463,13 @@ sub stringify_column {
 
 =head2 do_pager
 
+   Sets the pager template argument ($r->{template_args}{pager})
+   to a Class::DBI::Pager object based on the rows_per_page
+   value set in the configuration of the application.
+
+   This pager is used via the pager macro in TT Templates, and
+   is also accessible via Mason.
+
 =cut
 
 sub do_pager {
@@ -469,6 +484,16 @@ sub do_pager {
 
 =head2 order
 
+    Returns the SQL order syntax based on the order parameter passed
+    to the request, and the valid columns.. i.e. 'title ASC' or 'date_created DESC'.
+
+    $sql .= $self->order($r);
+
+    If the order column is not a column of this table,
+    or an order argument is not passed, then the return value is undefined.
+
+    Note: the returned value does not start with a space.
+
 =cut
 
 sub order {
@@ -481,8 +506,27 @@ sub order {
     return $order;
 }
 
+=head2 setup
+
+  This method is inherited from Maypole::Model::Base and calls setup_database,
+  which uses Class::DBI::Loader to create and load Class::DBI classes from
+  the given database schema.
+
+=cut
+
 =head2 setup_database
 
+The $opts argument is a hashref of options.  The "options" key is a hashref of
+Database connection options . Other keys may be various Loader arguments or
+flags.  It has this form:
+ {
+   # DB connection options
+   options { AutoCommit => 1 , ... },
+   # Loader args
+   relationships => 1,
+   ...
+ }
+
 =cut
 
 sub setup_database {