From: Justin Guenther <jguenther@cpan.org>
Date: Fri, 24 Mar 2006 07:16:39 +0000 (+0000)
Subject: changed formatting for arguments/return values in method docs
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=27f01d1f4fc106e0d27a13c6f6c9d5fa131e9447;p=dbsrgits%2FDBIx-Class-Historic.git

changed formatting for arguments/return values in method docs
---

diff --git a/lib/DBIx/Class/AccessorGroup.pm b/lib/DBIx/Class/AccessorGroup.pm
index b8079fc..9ef0a51 100644
--- a/lib/DBIx/Class/AccessorGroup.pm
+++ b/lib/DBIx/Class/AccessorGroup.pm
@@ -20,9 +20,15 @@ getters and setters.
 
 =head2 mk_group_accessors
 
-Creates a set of accessors in a given group.
+=over 4
+
+=item Arguments: $group, @fieldspec
+
+Returns: none
+
+=back
 
-=head3 Arguments: $group, @fieldspec
+Creates a set of accessors in a given group.
 
 $group is the name of the accessor group for the generated accessors; they
 will call get_$group($field) on get and set_$group($field, $value) on set.
@@ -31,8 +37,6 @@ will call get_$group($field) on get and set_$group($field, $value) on set.
 this is used as both field and accessor name, if a listref it is expected to
 be of the form [ $accessor, $field ].
 
-=head3 Return value: none
-
 =cut
 
 sub mk_group_accessors {
@@ -80,14 +84,18 @@ sub mk_group_accessors {
 
 =head2 mk_group_ro_accessors
 
+=over 4
+
+=item Arguments: $group, @fieldspec
+
+Returns: none
+
+=back
+
 Creates a set of read only accessors in a given group. Identical to
 <L:/mk_group_accessors> but accessors will throw an error if passed a value
 rather than setting the value.
 
-=head3 Arguments: $group, @fieldspec
-
-=head3 Return value: none
-
 =cut
 
 sub mk_group_ro_accessors {
@@ -98,14 +106,18 @@ sub mk_group_ro_accessors {
 
 =head2 mk_group_wo_accessors
 
+=over 4
+
+=item Arguments: $group, @fieldspec
+
+Returns: none
+
+=back
+
 Creates a set of write only accessors in a given group. Identical to
 <L:/mk_group_accessors> but accessors will throw an error if not passed a
 value rather than getting the value.
 
-=head3 Arguments: $group, @fieldspec
-
-=head3 Return value: none
-
 =cut
 
 sub mk_group_wo_accessors {
@@ -116,12 +128,16 @@ sub mk_group_wo_accessors {
 
 =head2 make_group_accessor
 
-Returns a single accessor in a given group; called by mk_group_accessors
-for each entry in @fieldspec.
+=over 4
+
+=item Arguments: $group, $field
 
-=head3 Arguments: $group, $field
+Returns: $sub (\CODE)
 
-=head3 Return value: $sub (\CODE)
+=back
+
+Returns a single accessor in a given group; called by mk_group_accessors
+for each entry in @fieldspec.
 
 =cut
 
@@ -146,12 +162,16 @@ sub make_group_accessor {
 
 =head2 make_group_ro_accessor
 
-Returns a single read-only accessor in a given group; called by
-mk_group_ro_accessors for each entry in @fieldspec.
+=over 4
+
+=item Arguments: $group, $field
 
-=head3 Arguments: $group, $field
+Returns: $sub (\CODE)
 
-=head3 Return value: $sub (\CODE)
+=back
+
+Returns a single read-only accessor in a given group; called by
+mk_group_ro_accessors for each entry in @fieldspec.
 
 =cut
 
@@ -176,12 +196,16 @@ sub make_group_ro_accessor {
 
 =head2 make_group_wo_accessor
 
-Returns a single write-only accessor in a given group; called by
-mk_group_wo_accessors for each entry in @fieldspec.
+=over 4
+
+=item Arguments: $group, $field
+
+Returns: $sub (\CODE)
 
-=head3 Arguments: $group, $field
+=back
 
-=head3 Return value: $sub (\CODE)
+Returns a single write-only accessor in a given group; called by
+mk_group_wo_accessors for each entry in @fieldspec.
 
 =cut
 
@@ -206,12 +230,16 @@ sub make_group_wo_accessor {
 
 =head2 get_simple
 
-Simple getter for hash-based objects which returns the value for the field
-name passed as an argument.
+=over 4
 
-=head3 Arguments: $field
+=item Arguments: $field
 
-=head3 Return value: $value
+Returns: $value
+
+=back
+
+Simple getter for hash-based objects which returns the value for the field
+name passed as an argument.
 
 =cut
 
@@ -222,12 +250,16 @@ sub get_simple {
 
 =head2 set_simple
 
-Simple setter for hash-based objects which sets and then returns the value
-for the field name passed as an argument.
+=over 4
+
+=item Arguments: $field, $new_value
 
-=head3 Arguments: $field, $new_value
+Returns: $new_value
 
-=head3 Return value: $new_value
+=back
+
+Simple setter for hash-based objects which sets and then returns the value
+for the field name passed as an argument.
 
 =cut
 
@@ -238,14 +270,18 @@ sub set_simple {
 
 =head2 get_component_class
 
+=over 4
+
+=item Arguments: $name
+
+Returns: $component_class
+
+=back
+
 Returns the class name for a component; returns an object key if called on
 an object, or attempts to return classdata referenced by _$name if called
 on a class.
 
-=head3 Arguments: $name
-
-=head3 Return value: $component_class
-
 =cut
 
 sub get_component_class {
@@ -260,14 +296,18 @@ sub get_component_class {
 
 =head2 set_component_class
 
+=over 4
+
+=item Arguments: $name, $new_component_class
+
+Returns: $new_component_class
+
+=back
+
 Sets a component class name; attempts to require the class before setting
 but does not error if unable to do so. Sets an object key of the given name
 if called or an object or classdata called _$name if called on a class.
 
-=head3 Arguments: $name, $new_component_class
-
-=head3 Return value: $new_component_class
-
 =cut
 
 sub set_component_class {
diff --git a/lib/DBIx/Class/Relationship/Base.pm b/lib/DBIx/Class/Relationship/Base.pm
index 343c0d0..9ea8cff 100644
--- a/lib/DBIx/Class/Relationship/Base.pm
+++ b/lib/DBIx/Class/Relationship/Base.pm
@@ -21,7 +21,11 @@ methods, for predefined ones, look in L<DBIx::Class::Relationship>.
 
 =head2 add_relationship
 
-=head3 Arguments: ('relname', 'Foreign::Class', $cond, $attrs)
+=over 4
+
+=item Arguments: ('relname', 'Foreign::Class', $cond, $attrs)
+
+=back
 
   __PACKAGE__->add_relationship('relname', 'Foreign::Class', $cond, $attrs);
 
@@ -62,9 +66,10 @@ command immediately before C<JOIN>.
 An arrayref containing a list of accessors in the foreign class to create in
 the main class. If, for example, you do the following:
   
-  MyDB::Schema::CD->might_have(liner_notes => 'MyDB::Schema::LinerNotes', undef, {
-    proxy => [ qw/notes/ ],
-  });
+  MyDB::Schema::CD->might_have(liner_notes => 'MyDB::Schema::LinerNotes',
+    undef, {
+      proxy => [ qw/notes/ ],
+    });
   
 Then, assuming MyDB::Schema::LinerNotes has an accessor named notes, you can do:
 
@@ -85,7 +90,11 @@ created, which calls C<create_related> for the relationship.
 
 =head2 register_relationship
 
-=head3 Arguments: ($relname, $rel_info)
+=over 4
+
+=item Arguments: ($relname, $rel_info)
+
+=back
 
 Registers a relationship on the class. This is called internally by
 L<DBIx::Class::ResultSourceProxy> to set up Accessors and Proxies.
@@ -94,11 +103,20 @@ L<DBIx::Class::ResultSourceProxy> to set up Accessors and Proxies.
 
 sub register_relationship { }
 
-=head2 related_resultset($name)
+=head2 related_resultset
+
+=over 4
+
+=item Arguments: ($relationship_name)
+
+=item Returns: $related_resultset
+
+=back
 
-  $rs = $obj->related_resultset('related_table');
+  $rs = $cd->related_resultset('artist');
 
-Returns a L<DBIx::Class::ResultSet> for the relationship named $name.
+Returns a L<DBIx::Class::ResultSet> for the relationship named
+$relationship_name.
 
 =cut
 
@@ -160,7 +178,7 @@ sub search_related {
 
 Returns the count of all the items in the related resultset, restricted by the
 current item or where conditions. Can be called on a
-L<DBIx::Classl::Manual::Glossary/"ResultSet"> or a
+L<DBIx::Class::Manual::Glossary/"ResultSet"> or a
 L<DBIx::Class::Manual::Glossary/"Row"> object.
 
 =cut
@@ -175,9 +193,9 @@ sub count_related {
   my $new_obj = $obj->new_related('relname', \%col_data);
 
 Create a new item of the related foreign class. If called on a
-L<DBIx::Class::Manual::Glossary/"Row"> object, it will magically
-set any primary key values into foreign key columns for you. The newly
-created item will not be saved into your storage until you call C<insert>
+L<DBIx::Class::Manual::Glossary/"Row"> object, it will magically set any
+primary key values into foreign key columns for you. The newly created item
+will not be saved into your storage until you call L<DBIx::Class::Row/insert>
 on it.
 
 =cut
@@ -210,7 +228,7 @@ sub create_related {
   my $found_item = $obj->find_related('relname', @pri_vals | \%pri_vals);
 
 Attempt to find a related object using its primary key or unique constraints.
-See C<find> in L<DBIx::Class::ResultSet> for details.
+See L<DBIx::Class::ResultSet/find> for details.
 
 =cut
 
@@ -224,8 +242,8 @@ sub find_related {
 
   my $new_obj = $obj->find_or_create_related('relname', \%col_data);
 
-Find or create an item of a related class. See C<find_or_create> in
-L<DBIx::Class::ResultSet> for details.
+Find or create an item of a related class. See
+L<DBIx::Class::ResultSet/"find_or_create"> for details.
 
 =cut
 
@@ -243,8 +261,8 @@ related object. This is used to associate previously separate objects, for
 example, to set the correct author for a book, find the Author object, then
 call set_from_related on the book.
 
-The columns are only set in the local copy of the object, call C<update> to set
-them in the storage.
+The columns are only set in the local copy of the object, call L</update> to
+set them in the storage.
 
 =cut
 
@@ -271,8 +289,8 @@ sub set_from_related {
 
   $book->update_from_related('author', $author_obj);
 
-As C<set_from_related>, but the changes are immediately updated onto your
-storage.
+The same as L</"set_from_related">, but the changes are immediately updated
+in storage.
 
 =cut
 
diff --git a/lib/DBIx/Class/ResultSet.pm b/lib/DBIx/Class/ResultSet.pm
index 461a837..093a456 100644
--- a/lib/DBIx/Class/ResultSet.pm
+++ b/lib/DBIx/Class/ResultSet.pm
@@ -53,7 +53,11 @@ In the examples below, the following table classes are used:
 
 =head2 new
 
-=head3 Arguments: ($source, \%$attrs)
+=over 4
+
+=item Arguments: ($source, \%$attrs)
+
+=back
 
 The resultset constructor. Takes a source object (usually a
 L<DBIx::Class::ResultSourceProxy::Table>) and an attribute hash (see
@@ -232,7 +236,11 @@ sub search_literal {
 
 =head2 find
 
-=head3 Arguments: (@colvalues) | (\%cols, \%attrs?)
+=over 4
+
+=item Arguments: (@colvalues) | (\%cols, \%attrs?)
+
+=back
 
 Finds a row based on its primary key or unique constraint. For example:
 
@@ -368,7 +376,11 @@ sub search_like {
 
 =head2 slice
 
-=head3 Arguments: ($first, $last)
+=over 4
+
+=item Arguments: ($first, $last)
+
+=back
 
 Returns a subset of elements from the resultset.
 
@@ -633,7 +645,11 @@ sub first {
 
 =head2 update
 
-=head3 Arguments: (\%values)
+=over 4
+
+=item Arguments: (\%values)
+
+=back
 
 Sets the specified columns in the resultset to the supplied values.
 
@@ -644,12 +660,17 @@ sub update {
   $self->throw_exception("Values for update must be a hash")
     unless ref $values eq 'HASH';
   return $self->result_source->storage->update(
-           $self->result_source->from, $values, $self->{cond});
+    $self->result_source->from, $values, $self->{cond}
+  );
 }
 
 =head2 update_all
 
-=head3 Arguments: (\%values)
+=over 4
+
+=item Arguments: (\%values)
+
+=back
 
 Fetches all objects and updates them one at a time.  Note that C<update_all>
 will run cascade triggers while L</update> will not.
@@ -705,9 +726,11 @@ sub delete {
         $del->{$1} = $self->{cond}{$key};
       }
     }
+
   } else {
     $self->throw_exception(
-      "Can't delete on resultset with condition unless hash or array");
+      "Can't delete on resultset with condition unless hash or array"
+    );
   }
 
   $self->result_source->storage->delete($self->result_source->from, $del);
@@ -746,7 +769,11 @@ sub pager {
 
 =head2 page
 
-=head3 Arguments: ($page_num)
+=over 4
+
+=item Arguments: ($page_num)
+
+=back
 
 Returns a new resultset for the specified page.
 
@@ -761,7 +788,11 @@ sub page {
 
 =head2 new_result
 
-=head3 Arguments: (\%vals)
+=over 4
+
+=item Arguments: (\%vals)
+
+=back
 
 Creates a result in the resultset's result class.
 
@@ -786,7 +817,11 @@ sub new_result {
 
 =head2 create
 
-=head3 Arguments: (\%vals)
+=over 4
+
+=item Arguments: (\%vals)
+
+=back
 
 Inserts a record into the resultset and returns the object.
 
@@ -803,7 +838,11 @@ sub create {
 
 =head2 find_or_create
 
-=head3 Arguments: (\%vals, \%attrs?)
+=over 4
+
+=item Arguments: (\%vals, \%attrs?)
+
+=back
 
   $class->find_or_create({ key => $val, ... });
 
@@ -993,6 +1032,8 @@ sub throw_exception {
 
 =head1 ATTRIBUTES
 
+XXX: FIXME: Attributes docs need clearing up
+
 The resultset takes various attributes that modify its behavior. Here's an
 overview of them:
 
@@ -1004,7 +1045,11 @@ descending order on the column `year'.
 
 =head2 columns
 
-=head3 Arguments: (arrayref)
+=over 4
+
+=item Arguments: (\@columns)
+
+=back
 
 Shortcut to request a particular set of columns to be retrieved.  Adds
 C<me.> onto the start of any column without a C<.> in it and sets C<select>
@@ -1013,7 +1058,11 @@ use the C<cols> attribute, as in earlier versions of DBIC.)
 
 =head2 include_columns
 
-=head3 Arguments: (arrayref)
+=over 4
+
+=item Arguments: (\@columns)
+
+=back
 
 Shortcut to include additional columns in the returned results - for example
 
@@ -1027,7 +1076,11 @@ passed to object inflation
 
 =head2 select
 
-=head3 Arguments: (arrayref)
+=over 4
+
+=item Arguments: (\@columns)
+
+=back
 
 Indicates which columns should be selected from the storage. You can use
 column names, or in the case of RDBMS back ends, function or stored procedure
@@ -1047,7 +1100,11 @@ return a column named C<count(employeeid)> in the above example.
 
 =head2 as
 
-=head3 Arguments: (arrayref)
+=over 4
+
+=item Arguments: (\@names)
+
+=back
 
 Indicates column names for object inflation. This is used in conjunction with
 C<select>, usually when C<select> contains one or more function or stored
@@ -1126,7 +1183,11 @@ below.
 
 =head2 prefetch
 
-=head3 Arguments: arrayref/hashref
+=over 4
+
+=item Arguments: (\@relationships)
+
+=back
 
 Contains one or more relationships that should be fetched along with the main 
 query (when they are accessed afterwards they will have already been
@@ -1163,7 +1224,11 @@ with an accessor type of 'single' or 'filter').
 
 =head2 from
 
-=head3 Arguments: (arrayref)
+=over 4
+
+=item Arguments: (\@array)
+
+=back
 
 The C<from> attribute gives you manual control over the C<FROM> clause of SQL
 statements generated by L<DBIx::Class>, allowing you to express custom C<JOIN>
@@ -1252,12 +1317,24 @@ with a father in the person table, we could explicitly use C<INNER JOIN>:
 
 =head2 page
 
+=over 4
+
+=item Arguments: ($page)
+
+=back
+
 For a paged resultset, specifies which page to retrieve.  Leave unset
 for an unpaged resultset.
 
 =head2 rows
 
-For a paged resultset, how many rows per page:
+=over 4
+
+=item Arguments: ($rows)
+
+=back
+
+For a paged resultset, specifies how many rows are in each page:
 
   rows => 10
 
@@ -1265,7 +1342,11 @@ Can also be used to simulate an SQL C<LIMIT>.
 
 =head2 group_by
 
-=head3 Arguments: (arrayref)
+=over 4
+
+=item Arguments: (\@columns)
+
+=back
 
 A arrayref of columns to group by. Can include columns of joined tables.
 
diff --git a/lib/DBIx/Class/ResultSource.pm b/lib/DBIx/Class/ResultSource.pm
index bdf01f1..cfa8bc9 100644
--- a/lib/DBIx/Class/ResultSource.pm
+++ b/lib/DBIx/Class/ResultSource.pm
@@ -207,7 +207,11 @@ sub columns {
 
 =head2 set_primary_key
 
-=head3 Arguments: (@cols)
+=over 4
+
+=item Arguments: (@cols)
+
+=back
 
 Defines one or more columns as primary key for this source. Should be
 called after C<add_columns>.
@@ -247,8 +251,12 @@ Declare a unique constraint on this source. Call once for each unique
 constraint. Unique constraints are used when you call C<find> on a
 L<DBIx::Class::ResultSet>, only columns in the constraint are searched,
 
-  # For e.g. UNIQUE (column1, column2)
-  __PACKAGE__->add_unique_constraint(constraint_name => [ qw/column1 column2/ ]);
+e.g.,
+
+  # For UNIQUE (column1, column2)
+  __PACKAGE__->add_unique_constraint(
+    constraint_name => [ qw/column1 column2/ ],
+  );
 
 =cut
 
@@ -359,7 +367,8 @@ relationship.
 
 sub add_relationship {
   my ($self, $rel, $f_source_name, $cond, $attrs) = @_;
-  $self->throw_exception("Can't create relationship without join condition") unless $cond;
+  $self->throw_exception("Can't create relationship without join condition")
+    unless $cond;
   $attrs ||= {};
 
   my %rels = %{ $self->_relationships };
@@ -409,7 +418,11 @@ sub relationships {
 
 =head2 relationship_info
 
-=head3 Arguments: ($relname)
+=over 4
+
+=item Arguments: ($relname)
+
+=back
 
 Returns the relationship information for the specified relationship name
 
@@ -422,7 +435,11 @@ sub relationship_info {
 
 =head2 has_relationship
 
-=head3 Arguments: ($rel)
+=over 4
+
+=item Arguments: ($rel)
+
+=back
 
 Returns 1 if the source has a relationship of this name, 0 otherwise.
 
@@ -435,7 +452,11 @@ sub has_relationship {
 
 =head2 resolve_join
 
-=head3 Arguments: ($relation)
+=over 4
+
+=item Arguments: ($relation)
+
+=back
 
 Returns the join structure required for the related result source
 
@@ -470,7 +491,11 @@ sub resolve_join {
 
 =head2 resolve_condition
 
-=head3 Arguments: ($cond, $as, $alias|$object)
+=over 4
+
+=item Arguments: ($cond, $as, $alias|$object)
+
+=back
 
 Resolves the passed condition to a concrete query fragment. If given an alias,
 returns a join condition; if given an object, inverts that object to produce
@@ -485,8 +510,10 @@ sub resolve_condition {
     my %ret;
     while (my ($k, $v) = each %{$cond}) {
       # XXX should probably check these are valid columns
-      $k =~ s/^foreign\.// || $self->throw_exception("Invalid rel cond key ${k}");
-      $v =~ s/^self\.// || $self->throw_exception("Invalid rel cond val ${v}");
+      $k =~ s/^foreign\.// ||
+	$self->throw_exception("Invalid rel cond key ${k}");
+      $v =~ s/^self\.// ||
+	$self->throw_exception("Invalid rel cond val ${v}");
       if (ref $for) { # Object
         #warn "$self $k $for $v";
         $ret{$k} = $for->get_column($v);
@@ -507,7 +534,11 @@ sub resolve_condition {
 
 =head2 resolve_prefetch
 
-=head3 Arguments: (hashref/arrayref/scalar)
+=over 4
+
+=item Arguments: (hashref/arrayref/scalar)
+
+=back
 
 Accepts one or more relationships for the current source and returns an
 array of column names for each of those relationships. Column names are
@@ -608,7 +639,11 @@ sub resolve_prefetch {
 
 =head2 related_source
 
-=head3 Arguments: ($relname)
+=over 4
+
+=item Arguments: ($relname)
+
+=back
 
 Returns the result source object for the given relationship
 
@@ -624,7 +659,11 @@ sub related_source {
 
 =head2 related_class
 
-=head3 Arguments: ($relname)
+=over 4
+
+=item Arguments: ($relname)
+
+=back
 
 Returns the class object for the given relationship
 
@@ -661,9 +700,15 @@ Specify here any attributes you wish to pass to your specialised resultset.
 
 sub resultset {
   my $self = shift;
-  $self->throw_exception('resultset does not take any arguments. If you want another resultset, call it on the schema instead.') if scalar @_;
-  return $self->{_resultset} if ref $self->{_resultset} eq $self->resultset_class;
-  return $self->{_resultset} = $self->resultset_class->new($self, $self->{resultset_attributes});
+  $self->throw_exception(
+    'resultset does not take any arguments. If you want another resultset, '.
+    'call it on the schema instead.'
+  ) if scalar @_;
+  return $self->{_resultset}
+    if ref $self->{_resultset} eq $self->resultset_class;
+  return $self->{_resultset} = $self->resultset_class->new(
+    $self, $self->{resultset_attributes}
+  );
 }
 
 =head2 throw_exception
diff --git a/lib/DBIx/Class/Row.pm b/lib/DBIx/Class/Row.pm
index 85a0551..7c5cf9a 100644
--- a/lib/DBIx/Class/Row.pm
+++ b/lib/DBIx/Class/Row.pm
@@ -36,9 +36,11 @@ sub new {
   $class = ref $class if ref $class;
   my $new = bless { _column_data => {} }, $class;
   if ($attrs) {
-    $new->throw_exception("attrs must be a hashref") unless ref($attrs) eq 'HASH';
+    $new->throw_exception("attrs must be a hashref")
+      unless ref($attrs) eq 'HASH';
     while (my ($k, $v) = each %$attrs) {
-      $new->throw_exception("No such column $k on $class") unless $class->has_column($k);
+      $new->throw_exception("No such column $k on $class")
+	unless $class->has_column($k);
       $new->store_column($k => $v);
     }
   }
@@ -371,7 +373,11 @@ sub is_changed {
 
 =head2 register_column
 
-=head3 Arguments: ($column, $column_info)
+=over 4
+
+=item Arguments: ($column, $column_info)
+
+=back
 
   Registers a column on the class. If the column_info has an 'accessor' key,
   creates an accessor named after the value if defined; if there is no such
diff --git a/lib/DBIx/Class/Schema.pm b/lib/DBIx/Class/Schema.pm
index 17c1602..3d7e681 100644
--- a/lib/DBIx/Class/Schema.pm
+++ b/lib/DBIx/Class/Schema.pm
@@ -57,7 +57,11 @@ particular which module inherits off which.
 
 =head2 register_class
 
-=head3 Arguments: ($moniker, $component_class)
+=over 4
+
+=item Arguments: ($moniker, $component_class)
+
+=back
 
 Registers a class which isa L<DBIx::Class::ResultSourceProxy>. Equivalent to
 calling
@@ -73,7 +77,11 @@ sub register_class {
 
 =head2 register_source
 
-=head3 Arguments: ($moniker, $result_source)
+=over 4
+
+=item Arguments: ($moniker, $result_source)
+
+=back
 
 Registers the L<DBIx::Class::ResultSource> in the schema with the given
 moniker.
@@ -95,9 +103,13 @@ sub register_source {
 
 =head2 class
 
-=head3 Arguments: ($moniker)
+=over 4
+
+=item Arguments: ($moniker)
 
-=head3 Returns: $classname
+=item Returns: $classname
+
+=back
 
 Retrieves the result class name for the given moniker.
 
@@ -114,9 +126,13 @@ sub class {
 
 =head2 source
 
-=head3 Arguments: ($moniker)
+=over 4
+
+=item Arguments: ($moniker)
+
+=item Returns: $result_source
 
-=head3 Returns: $result_source
+=back
 
   my $source = $schema->source('Book');
 
@@ -138,7 +154,11 @@ sub source {
 
 =head2 sources
 
-=head3 Returns: @source_monikers
+=over 4
+
+=item Returns: @source_monikers
+
+=back
 
 Returns the source monikers of all source registrations on this schema.
 
@@ -152,9 +172,13 @@ sub sources { return keys %{shift->source_registrations}; }
 
 =head2 resultset
 
-=head3 Arguments: ($moniker)
+=over 4
+
+=item Arguments: ($moniker)
 
-=head3 Returns: $result_set
+=item Returns: $result_set
+
+=back
 
   my $rs = $schema->resultset('DVD');
 
@@ -169,7 +193,11 @@ sub resultset {
 
 =head2 load_classes
 
-=head3 Arguments: @classes?, { $namespace => [ @classes ] }+
+=over 4
+
+=item Arguments: @classes?, { $namespace => [ @classes ] }+
+
+=back
 
 With no arguments, this method uses L<Module::Find> to find all classes under
 the schema's namespace. Otherwise, this method loads the classes you specify
@@ -256,9 +284,13 @@ sub load_classes {
 
 =head2 compose_connection
 
-=head3 Arguments: ($target_namespace, @db_info)
+=over 4
+
+=item Arguments: ($target_namespace, @db_info)
 
-=head3 Returns: $new_schema
+=item Returns: $new_schema
+
+=back
 
 Calls L<DBIx::Class::schema/"compose_namespace"> to the target namespace,
 calls L<DBIx::Class::Schema/connection>(@db_info) on the new schema, then
@@ -315,9 +347,13 @@ sub compose_connection {
 
 =head2 compose_namespace
 
-=head3 Arguments: $target_namespace, $additional_base_class?
+=over 4
+
+=item Arguments: $target_namespace, $additional_base_class?
 
-=head3 Returns: $new_schema
+=item Returns: $new_schema
+
+=back
 
 For each L<DBIx::Class::ResultSource> in the schema, this method creates a
 class in the target namespace (e.g. $target_namespace::CD,
@@ -373,7 +409,11 @@ sub compose_namespace {
 
 =head2 setup_connection_class
 
-=head3 Arguments: ($target, @info)
+=over 4
+
+=item Arguments: ($target, @info)
+
+=back
 
 Sets up a database connection class to inject between the schema and the
 subclasses that the schema creates.
@@ -389,9 +429,13 @@ sub setup_connection_class {
 
 =head2 connection
 
-=head3 Arguments: (@args)
+=over 4
+
+=item Arguments: (@args)
 
-=head3 Returns: $new_schema
+=item Returns: $new_schema
+
+=back
 
 Instantiates a new Storage object of type
 L<DBIx::Class::Schema/"storage_type"> and passes the arguments to
@@ -418,9 +462,13 @@ sub connection {
 
 =head2 connect
 
-=head3 Arguments: (@info)
+=over 4
+
+=item Arguments: (@info)
+
+=item Returns: $new_schema
 
-=head3 Returns: $new_schema
+=back
 
 This is a convenience method. It is equivalent to calling
 $schema->clone->connection(@info). See L</connection> and L</clone> for more
@@ -462,10 +510,13 @@ sub txn_rollback { shift->storage->txn_rollback }
 
 =head2 txn_do
 
-=head3 Arguments: (C<$coderef>, @coderef_args?)
+=over 4
+
+=item Arguments: (C<$coderef>, @coderef_args?)
+
+=item Returns: The return value of $coderef
 
-=head3 Returns: (C<$return_value> | C<@return_values> | C<undef>) for scalar,
-list and void contexts, respectively
+=back
 
 Executes C<$coderef> with (optional) arguments C<@coderef_args> atomically,
 returning its result (if any). If an exception is caught, a rollback is issued
@@ -566,7 +617,11 @@ sub txn_do {
 
 =head2 clone
 
-=head3 Returns: $new_schema
+=over 4
+
+=item Returns: $new_schema
+
+=back
 
 Clones the schema and its associated result_source objects and returns the
 copy.
@@ -586,7 +641,11 @@ sub clone {
 
 =head2 populate
 
-=head3 Arguments: ($moniker, \@data);
+=over 4
+
+=item Arguments: ($moniker, \@data);
+
+=back
 
 Populates the source registered with the given moniker with the supplied data.
 @data should be a list of listrefs -- the first containing column names, the