From: Shawn M Moore <sartak@gmail.com>
Date: Thu, 30 Apr 2009 02:42:33 +0000 (-0400)
Subject: Another pass at the FAQ for legibility
X-Git-Tag: 0.77~17
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=6c17df8f63ace7b46c1728f04ad470348f9fea05;p=gitmo%2FMoose.git

Another pass at the FAQ for legibility
---

diff --git a/lib/Moose/Cookbook/FAQ.pod b/lib/Moose/Cookbook/FAQ.pod
index db1b126..106e5d7 100644
--- a/lib/Moose/Cookbook/FAQ.pod
+++ b/lib/Moose/Cookbook/FAQ.pod
@@ -91,7 +91,7 @@ curve.
 
 =head3 How do I make non-Moose constructors work with Moose?
 
-Usually the correct approach to subclassing a non Moose class is
+Usually the correct approach to subclassing a non-Moose class is
 delegation.  Moose makes this easy using the C<handles> keyword,
 coercions, and C<lazy_build>, so subclassing is often not the
 ideal route.
@@ -151,7 +151,7 @@ mailing list are great ways to get help finding the best approach.
 =head3 How do I tell Moose to use get/set accessors?
 
 The easiest way to accomplish this is to use the C<reader> and
-C<writer> attribute options. Here is some example code:
+C<writer> attribute options:
 
   has 'bar' => (
       isa    => 'Baz',
@@ -163,20 +163,23 @@ Moose will still take advantage of type constraints, triggers, etc.
 when creating these methods.
 
 If you do not like this much typing, and wish it to be a default for your
-class, please see L<MooseX::FollowPBP>. This will allow you to write:
+classes, please see L<MooseX::FollowPBP>. This extension will allow you to
+write:
 
   has 'bar' => (
       isa => 'Baz',
       is  => 'rw',
   );
 
-And have Moose create separate C<get_bar> and C<set_bar> methods
+Moose will create separate C<get_bar> and C<set_bar> methods
 instead of a single C<bar> method.
 
 NOTE: This B<cannot> be set globally in Moose, as that would break
-other classes which are built with Moose.
+other classes which are built with Moose. You can still save on typing
+by defining a new L<MyApp::Moose> that exports Moose's sugar and then
+turns on L<MooseX::FollowPBP>. See L<Moose::Cookbook::Extending::Recipe4>.
 
-=head3 How can I get Moose to inflate/deflate values in the accessor?
+=head3 How can I inflate/deflate values in accessors?
 
 Well, the first question to ask is if you actually need both inflate
 and deflate.
@@ -184,9 +187,7 @@ and deflate.
 If you only need to inflate, then we suggest using coercions. Here is
 some basic sample code for inflating a L<DateTime> object:
 
-  subtype 'DateTime'
-      => as 'Object'
-      => where { $_->isa('DateTime') };
+  class_type 'DateTime';
 
   coerce 'DateTime'
       => from 'Str'
@@ -194,8 +195,8 @@ some basic sample code for inflating a L<DateTime> object:
 
   has 'timestamp' => (is => 'rw', isa => 'DateTime', coerce => 1);
 
-This creates a custom subtype for L<DateTime> objects, then attaches
-a coercion to that subtype. The C<timestamp> attribute is then told
+This creates a custom type for L<DateTime> objects, then attaches
+a coercion to that type. The C<timestamp> attribute is then told
 to expect a C<DateTime> type, and to try to coerce it. When a C<Str>
 type is given to the C<timestamp> accessor, it will attempt to
 coerce the value into a C<DateTime> object using the code in found
@@ -204,8 +205,8 @@ in the C<via> block.
 For a more comprehensive example of using coercions, see the
 L<Moose::Cookbook::Basics::Recipe5>.
 
-If you need to deflate your attribute, the current best practice is to
-add an C<around> modifier to your accessor. Here is some example code:
+If you need to deflate your attribute's value, the current best practice
+is to add an C<around> modifier to your accessor:
 
   # a timestamp which stores as
   # seconds from the epoch
@@ -239,10 +240,11 @@ method.
 
 We limit C<before> and C<after> because this lets you write more
 concise code. You do not have to worry about passing C<@_> to the
-original method, or forwarding its response (being careful to preserve
-context).
+original method, or forwarding its return value (being careful to
+preserve context).
 
-The C<around> method modifier has neither of these limitations.
+The C<around> method modifier has neither of these limitations, but
+is a little more verbose.
 
 =head3 Can I use C<before> to stop execution of a method?
 
@@ -251,42 +253,43 @@ measure then we suggest using C<around> instead. The C<around> method
 modifier is the only modifier which can gracefully prevent execution
 of the main method. Here is an example:
 
-  around 'baz' => sub {
-      my $next = shift;
-      my ($self, %options) = @_;
-      unless ($options->{bar} eq 'foo') {
-	return 'bar';
-      }
-      $next->($self, %options);
-  };
+    around 'baz' => sub {
+        my $next = shift;
+        my ($self, %options) = @_;
+        unless ($options->{bar} eq 'foo') {
+            return 'bar';
+        }
+        $next->($self, %options);
+    };
 
 By choosing not to call the C<$next> method, you can stop the
 execution of the main method.
 
 =head2 Type Constraints
 
-=head3 How can I have a custom error message for a type constraint?
+=head3 How can I provide a custom error message for a type constraint?
 
-Use the C<message> option when building the subtype, like so:
+Use the C<message> option when building the subtype:
 
   subtype 'NaturalLessThanTen'
       => as 'Natural'
       => where { $_ < 10 }
       => message { "This number ($_) is not less than ten!" };
 
-This will be called when a value fails to pass the C<NaturalLessThanTen>
-constraint check.
+This C<message> block will be called when a value fails to pass the
+C<NaturalLessThanTen> constraint check.
 
 =head3 Can I turn off type constraint checking?
 
-Not yet. This option will likely be coming in a future release.
+Not yet. This option will likely come in a future release.
 
 =head2 Roles
 
 =head3 How do I get Moose to call BUILD in all my composed roles?
 
-See L<Moose::Cookbook::WTF> and specifically the B<Why is BUILD
-not called for my composed roles?> question in the B<Roles> section.
+See L<Moose::Cookbook::WTF> and specifically the
+B<Why is BUILD not called for my composed roles?> question in the
+B<Roles> section.
 
 =head3 What are Traits, and how are they different from Roles?
 
@@ -296,8 +299,8 @@ to them by a short name ("Big" vs "MyApp::Role::Big").
 
 In Moose-speak, a I<Role> is usually composed into a I<class> at
 compile time, whereas a I<Trait> is usually composed into an instance
-of a class at runtime to add or modify the behavior of B<just that
-instance>.
+of a class at runtime to add or modify the behavior of
+B<just that instance>.
 
 Outside the context of Moose, traits and roles generally mean exactly the
 same thing. The original paper called them Traits, however Perl 6 will call