From: Dave Rolsky <autarch@urth.org>
Date: Tue, 3 Feb 2009 16:46:22 +0000 (+0000)
Subject: Tweaks for Classes document
X-Git-Tag: 0.66~11
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=3ac9038a977ef158b435c53622b83cc7b7c84a44;p=gitmo%2FMoose.git

Tweaks for Classes document
---

diff --git a/lib/Moose/Manual/Classes.pod b/lib/Moose/Manual/Classes.pod
index 8133bda..d91e41a 100644
--- a/lib/Moose/Manual/Classes.pod
+++ b/lib/Moose/Manual/Classes.pod
@@ -12,12 +12,12 @@ Using Moose is very simple, you just C<use Moose>:
 
   use Moose;
 
-That's it, you've now made a Moose-based class!
+That's it, you've made a class with Moose!
 
 There's actually a lot going on here under the hood, so let's step
-through it. The L<Moose> package does several things when you load it.
+through it.
 
-When you load Moose, you get a bunch of sugar functions exported into
+When you load L<Moose>, a bunch of sugar functions are exported into
 your class. These include things like C<extends>, C<has>, C<with>, and
 more. These functions are what you use to define your class. For
 example, you might define an attribute ...
@@ -31,14 +31,8 @@ example, you might define an attribute ...
 Attributes are described in the L<Moose::Manual::Attributes>
 documentation.
 
-Loading Moose in your class also turns on the C<strict> and
-C<warnings> pragmas in your class for you.
-
-The metaclass object an introspection API for your class. It is also
-used by Moose itself under the hood to add attributes, define parent
-classes, and so on. In fact, all of Moose's sugar does the real work
-by calling methods on this metaclass object (and other meta level
-objects).
+Loading Moose also turns enables C<strict> and C<warnings> pragmas in
+your class.
 
 When you load Moose, your class will become a subclass of
 L<Moose::Object>. The L<Moose::Object> class provides a default
@@ -46,15 +40,19 @@ constructor, destructor, as well as object construction helper
 methods. You can read more about this in the
 L<Moose::Manual::Construction> document.
 
-As a convenience, Moose creates a new class type with the name of your
-class, by calling the C<class_type> function in
-L<Moose::Util::Constraints>. See the L<Moose::Manual::Types> document
-for more about types.
+As a convenience, Moose creates a new class type for your class. See
+the L<Moose::Manual::Types> document to learn more about types.
 
 It also creates a L<Moose::Meta::Class> object for your class. This
 metaclass object is now available by calling a C<meta> method on your
 class, for example C<< Person->meta >>.
 
+The metaclass object provides an introspection API for your class. It
+is also used by Moose itself under the hood to add attributes, define
+parent classes, and so on. In fact, all of Moose's sugar does the real
+work by calling methods on this metaclass object (and other meta API
+objects).
+
 =head1 SUBCLASSING
 
 Moose provides a simple sugar function for declaring your parent
@@ -68,16 +66,15 @@ classes, C<extends>:
 
   has 'username' => ( is => 'rw' );
 
-When you call extends, Moose takes the class(es) you provide and makes
-those the parent of the current class. Note, that each call to
-C<extends> will I<reset> your parents, so for multiple inheritance you
-should provide all you parents at once, C<extends 'Foo', 'Bar'>.
+ote, that each call to C<extends> will I<reset> your parents. For
+multiple inheritance you must provide all the parents at once,
+C<extends 'Foo', 'Bar'>.
 
 You can use Moose to extend a non-Moose parent. However, when you do
 this, you will inherit the parent class's constructor (assuming it is
 also called C<new>). In that case, you will have to take care of
 initializing attributes manually, either in the parent's constructor,
-or in your subclass, and you will generally lose a lot of Moose magic.
+or in your subclass, and you will lose a lot of Moose magic.
 
 =head1 NO MOOSE
 
@@ -86,7 +83,7 @@ namespace. We recommend that you take advantage of this feature, since
 it just makes your classes "cleaner". You can do this by simply adding
 C<no Moose> at the end of your module file.
 
-What this does is delete the functions from your class's namespace, so
+This deletes Moose's sugar functions from your class's namespace, so
 that C<< Person->can('has') >> will no longer return true.
 
 =head1 MAKING IT FASTER
@@ -94,24 +91,25 @@ that C<< Person->can('has') >> will no longer return true.
 Moose has a feature called "immutabilization" that you can use to
 greatly speed up your classes at runtime. However, using it does incur
 a cost when your class is first being loaded. When you make your class
-immutable you tell Moose that you will not be changing it,
-specifically not adding any attributes, methods, roles, etc.
+immutable you tell Moose that you will not be changing it in the
+future. You will not adding any more attributes, methods, roles, etc.
 
-This allows Moose to generate code specific to your class for its
-constructor and other methods, making object construction much
-faster. It also makes some of the introspection methods faster as
-well.
+This allows Moose to generate code specific to your class. In
+particular, it creates an "inline" constructor, making object
+construction much faster.
 
 To make your class immutable you simply call C<make_immutable> on your
 class's metaclass object.
 
+  __PACKAGE__->meta->make_immutable;
+
 =head1 AUTHOR
 
 Dave Rolsky E<lt>autarch@urth.orgE<gt>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2008 by Infinity Interactive, Inc.
+Copyright 2008-2009 by Infinity Interactive, Inc.
 
 L<http://www.iinteractive.com>