various doc improvements

[gitmo/MooseX-Role-Parameterized.git] / lib / MooseX / Role / Parameterized.pm

diff --git a/lib/MooseX/Role/Parameterized.pm b/lib/MooseX/Role/Parameterized.pm
index 83e88ed..2ec5f18 100644 (file)
--- a/lib/MooseX/Role/Parameterized.pm
+++ b/lib/MooseX/Role/Parameterized.pm
@@ -35,7 +35,7 @@ sub parameter {
     }
 }
 
-sub role {
+sub role (&) {
     my $caller         = shift;
     my $role_generator = shift;
     Class::MOP::Class->initialize($caller)->role_generator($role_generator);
@@ -49,18 +49,6 @@ sub init_meta {
     );
 }
 
-# give role a (&) prototype
-moose_around _make_wrapper => sub {
-    my $orig = shift;
-    my ($self, $caller, $sub, $fq_name) = @_;
-
-    if ($fq_name =~ /::role$/) {
-        return sub (&) { $sub->($caller, @_) };
-    }
-
-    return $orig->(@_);
-};
-
 sub has {
     my $caller = shift;
     my $meta   = $CURRENT_METACLASS || Class::MOP::Class->initialize($caller);
@@ -191,7 +179,6 @@ MooseX::Role::Parameterized - parameterized roles
     use MooseX::Role::Parameterized;
 
     parameter name => (
-        is       => 'ro',
         isa      => 'Str',
         required => 1,
     );
@@ -230,24 +217,24 @@ L<MooseX::Role::Parameterized::Tutorial>.
 
 =head1 DESCRIPTION
 
-Your parameterized role consists of two things: parameter declarations and a
-C<role> block.
+Your parameterized role consists of two new things: parameter declarations
+and a C<role> block.
 
 Parameters are declared using the L</parameter> keyword which very much
-resembles L<Moose/has>. You can use any option that L<Moose/has> accepts.
-These parameters will get their values when the consuming class (or role) uses
+resembles L<Moose/has>. You can use any option that L<Moose/has> accepts. The
+default value for the C<is> option is C<ro> as that's a very common case. These
+parameters will get their values when the consuming class (or role) uses
 L<Moose/with>. A parameter object will be constructed with these values, and
 passed to the C<role> block.
 
 The C<role> block then uses the usual L<Moose::Role> keywords to build up a
 role. You can shift off the parameter object to inspect what the consuming
-class provided as parameters. You can use the parameters to make your role
-customizable!
+class provided as parameters. You use the parameters to customize your
+role however you wish.
 
-There are many paths to parameterized roles (hopefully with a consistent enough
-API); I believe this to be the easiest and most flexible implementation.
-Coincidentally, Pugs has a very similar design (I'm not yet convinced that that
-is a good thing).
+There are many possible implementations for parameterized roles (hopefully with
+a consistent enough API); I believe this to be the easiest and most flexible
+design. Coincidentally, Pugs has an eerily similar design.
 
 =head1 CAVEATS
 
@@ -257,16 +244,36 @@ return though you can use parameters I<in your methods>!
 
 L<Moose::Role/alias> and L<Moose::Role/excludes> are not yet supported. I'm
 completely unsure of whether they should be handled by this module. Until we
-figure out a plan, both declaring and providing a parameter named C<alias> or
+figure out a plan, either declaring or providing a parameter named C<alias> or
 C<excludes> is an error.
 
 =head1 AUTHOR
 
 Shawn M Moore, C<< <sartak@bestpractical.com> >>
 
-=head1 SEE ALSO
+=head1 EXAMPLES
+
+=over 4
+
+=item L<MooseX::Role::Matcher>
+
+=item L<MooseX::Role::XMLRPC::Client>
+
+=item L<MooseX::RelatedClassRoles>
+
+=item L<WWW::Mechanize::TreeBuilder>
+
+=item L<TAEB::Action::Role::Item>
+
+=item L<KiokuDB::Role::Scan>
+
+=item L<Fey::Role::MakesAliasObjects>
+
+=item L<Fey::Role::HasAliasName>
+
+=item L<Fey::Role::SetOperation>
 
-L<MooseX::Role::Matcher>
+=back
 
 =cut