From: Dave Rolsky <autarch@urth.org>
Date: Sun, 18 Jan 2009 21:24:32 +0000 (+0000)
Subject: Lots of doc cleanups and fixes
X-Git-Tag: 0.16~11
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=cc87d262cc1088f38149ecd63892fbd2196d9c4e;p=gitmo%2FMooseX-AttributeHelpers.git

Lots of doc cleanups and fixes
---

diff --git a/lib/MooseX/AttributeHelpers/MethodProvider/List.pm b/lib/MooseX/AttributeHelpers/MethodProvider/List.pm
index 367d607..008a625 100644
--- a/lib/MooseX/AttributeHelpers/MethodProvider/List.pm
+++ b/lib/MooseX/AttributeHelpers/MethodProvider/List.pm
@@ -116,24 +116,24 @@ MooseX::AttributeHelpers::MethodProvider::List
    use MooseX::AttributeHelpers;
 
    has 'options' => (
-      metaclass  => 'Collection::List',
-      is         => 'rw',
-      isa        => 'ArrayRef[Str]',
-      default    => sub { [] },
-      auto_deref => 1,
-      provides   => {
-         map   => 'map_options',
-         grep  => 'filter_options',
-         find  => 'find_option',
-         first => 'first_option',
-         last  => 'last_option',
-         get   => 'get_option',
-         join  => 'join_options',
-         count => 'count_options',
-         empty => 'do_i_have_options',
-         sort  => 'sorted_options',
-
-      }
+       metaclass  => 'Collection::List',
+       is         => 'rw',
+       isa        => 'ArrayRef[Str]',
+       default    => sub { [] },
+       auto_deref => 1,
+       provides   => {
+           elements => 'all_options',
+           map      => 'map_options',
+           grep     => 'filter_options',
+           find     => 'find_option',
+           first    => 'first_option',
+           last     => 'last_option',
+           get      => 'get_option',
+           join     => 'join_options',
+           count    => 'count_options',
+           empty    => 'do_i_have_options',
+           sort     => 'sorted_options',
+       }
    );
 
    no Moose;
@@ -157,46 +157,56 @@ L<MooseX::AttributeHelpers::Collection::List>.
 =over 4
 
 =item B<count>
-Returns the number of elements of the list.
-   
+
+Returns the number of elements inthe list.
+
    $stuff = Stuff->new;
    $stuff->options(["foo", "bar", "baz", "boo"]);
-   
+
    my $count = $stuff->count_options;
    print "$count\n"; # prints 4
 
-=item B<empty> 
+=item B<empty>
+
 If the list is populated, returns true. Otherwise, returns false.
 
    $stuff->do_i_have_options ? print "Good boy.\n" : die "No options!\n" ;
 
 =item B<find>
-Returns the first element that returns true in the anonymous subroutine
-passed as argument.
+
+This method accepts a subroutine reference as its argument. That sub
+will receive each element of the list in turn. If it returns true for
+an element, that element will be returned by the C<find> method.
 
    my $found = $stuff->find_option( sub { $_[0] =~ /^b/ } );
    print "$found\n"; # prints "bar"
 
 =item B<grep>
-Returns every element of the list that returns true in the anonymous
-subroutine passed as argument.
+
+This method accepts a subroutine reference as its argument. This
+method returns every element for which that subroutine reference
+returns a true value.
 
    my @found = $stuff->filter_options( sub { $_[0] =~ /^b/ } );
    print "@found\n"; # prints "bar baz boo"
 
 =item B<map>
-Executes the anonymous subroutine given as argument sequentially
-for each element of the list.
+
+This method accepts a subroutine reference as its argument. The
+subroutine will be executed for each element of the list. It is
+expected to return a modified version of that element. The return
+value of the method is a list of the modified options.
 
    my @mod_options = $stuff->map_options( sub { $_[0] . "-tag" } );
    print "@mod_options\n"; # prints "foo-tag bar-tag baz-tag boo-tag"
 
 =item B<sort>
 
-Returns a sorted list of the elements. You can optionally provide a
-subroutine reference to sort with (as you can with the core C<sort>
-function). However, instead of using C<$a> and C<$b>, you will need to
-use C<$_[0]> and C<$_[1]> instead.
+Sorts and returns the elements of the list.
+
+You can provide an optional subroutine reference to sort with (as you
+can with the core C<sort> function). However, instead of using C<$a>
+and C<$b>, you will need to use C<$_[0]> and C<$_[1]> instead.
 
    # ascending ASCIIbetical
    my @sorted = $stuff->sort_options();
@@ -206,31 +216,36 @@ use C<$_[0]> and C<$_[1]> instead.
    print "@sorted_options\n"; # prints "foo boo baz bar"
 
 =item B<elements>
-Returns an element of the list by its index.
 
-   my $option = $stuff->get_option(1);
-   print "$option\n"; # prints "bar"
+Returns all of the elements of the list
+
+   my @option = $stuff->all_options;
+   print "@options\n"; # prints "foo bar baz boo"
 
 =item B<join>
+
 Joins every element of the list using the separator given as argument.
 
    my $joined = $stuff->join_options( ':' );
    print "$joined\n"; # prints "foo:bar:baz:boo"
 
 =item B<get>
+
 Returns an element of the list by its index.
 
    my $option = $stuff->get_option(1);
    print "$option\n"; # prints "bar"
 
 =item B<first>
-Returns the first element.
+
+Returns the first element of the list.
 
    my $first = $stuff->first_option;
    print "$first\n"; # prints "foo"
 
 =item B<last>
-Returns the last item.
+
+Returns the last element of the list.
 
    my $last = $stuff->last_option;
    print "$last\n"; # prints "boo"