Doc tweaks

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

diff --git a/lib/MooseX/Role/Parameterized/Tutorial.pm b/lib/MooseX/Role/Parameterized/Tutorial.pm
index eab3c8d..c20c40d 100644 (file)
--- a/lib/MooseX/Role/Parameterized/Tutorial.pm
+++ b/lib/MooseX/Role/Parameterized/Tutorial.pm
@@ -1,10 +1,12 @@
 package MooseX::Role::Parameterized::Tutorial;
 confess "Don't use this module, read it!";
 
-# ABSTRACT: why and how
-
 __END__
 
+=head1 NAME
+
+MooseX::Role::Parameterized::Tutorial - why and how
+
 =head1 MOTIVATION
 
 Roles are composable units of behavior. They are useful for factoring out
@@ -18,10 +20,10 @@ you don't want or need (see L<Moose::Cookbook::Roles::Recipe2> for more
 about C<alias> and C<excludes>).
 
 Because roles serve many different masters, they usually provide only the least
-common denominator of functionality. Not all consumers of a role have a C<>.
-Thus, more configurability than C<alias> and C<excludes> is required. Perhaps
-your role needs to know which method to call when it is done. Or what default
-value to use for its url attribute.
+common denominator of functionality. To empower roles further, more
+configurability than C<alias> and C<excludes> is required. Perhaps your role
+needs to know which method to call when it is done. Or what default value to
+use for its url attribute.
 
 Parameterized roles offer exactly this solution.
 
@@ -58,9 +60,9 @@ then passed to...
 =head3 C<role>
 
 C<role> takes a block of code that will be used to generate your role with its
-parameters bound. Here is where you put your regular role code: use C<has>,
-method modifiers, and so on. You receive as an argument the parameter object
-constructed by C<with>. You can access the parameters just like regular
+parameters bound. Here is where you declare parameterized components: use
+C<has>, method modifiers, and so on. You receive as an argument the parameter
+object constructed by C<with>. You can access the parameters just like regular
 attributes on that object (assuming you declared them readable).
 
 Each time you compose this parameterized role, the role {} block will be