From: Stevan Little <stevan.little@iinteractive.com>
Date: Mon, 17 Mar 2008 01:18:09 +0000 (+0000)
Subject: doc updates
X-Git-Tag: 0_55~269
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=004222dc591495492d18979bee465a5a4fcbd8d5;p=gitmo%2FMoose.git

doc updates
---

diff --git a/Changes b/Changes
index a04f042..cbd3a1c 100644
--- a/Changes
+++ b/Changes
@@ -1,6 +1,8 @@
 Revision history for Perl extension Moose
 
 0.41
+    ~~ numerous documentation updates ~~
+
     ** IMPORTANT NOTE **
     - the make_immutable keyword is now deprecated, don't
       use it in any new code and please fix your old code
diff --git a/lib/Moose.pm b/lib/Moose.pm
index 3ec025a..30fcf2e 100644
--- a/lib/Moose.pm
+++ b/lib/Moose.pm
@@ -381,11 +381,10 @@ L<Moose::Object>) this includes properly initializing all instance slots,
 setting defaults where appropriate, and performing any type constraint checking
 or coercion.
 
-=head1 EXPORTED FUNCTIONS
+=head1 PROVIDED METHODS
 
-Moose will export a number of functions into the class's namespace which
-may then be used to set up the class. These functions all work directly
-on the current class.
+Moose provides a number of methods to all your classes, mostly through the 
+inheritance of L<Moose::Object>. There is however, one exception.
 
 =over 4
 
@@ -393,6 +392,16 @@ on the current class.
 
 This is a method which provides access to the current class's metaclass.
 
+=back
+
+=head1 EXPORTED FUNCTIONS
+
+Moose will export a number of functions into the class's namespace which
+may then be used to set up the class. These functions all work directly
+on the current class.
+
+=over 4
+
 =item B<extends (@superclasses)>
 
 This function will set the superclass(es) for the current class.
@@ -404,8 +413,7 @@ superclasses still properly inherit from L<Moose::Object>.
 
 =item B<with (@roles)>
 
-This will apply a given set of C<@roles> to the local class. Role support
-is currently under heavy development; see L<Moose::Role> for more details.
+This will apply a given set of C<@roles> to the local class. 
 
 =item B<has $name =E<gt> %options>
 
@@ -424,7 +432,8 @@ accessor respectively, using the same name as the C<$name> of the attribute.
 
 If you need more control over how your accessors are named, you can use the
 I<reader>, I<writer> and I<accessor> options inherited from
-L<Class::MOP::Attribute>.
+L<Class::MOP::Attribute>, however if you use those, you won't need the I<is> 
+option.
 
 =item I<isa =E<gt> $type_name>
 
@@ -469,22 +478,6 @@ If an attribute is marked as lazy it B<must> have a default supplied.
 This tells the accessor whether to automatically dereference the value returned.
 This is only legal if your C<isa> option is either C<ArrayRef> or C<HashRef>.
 
-=item I<metaclass =E<gt> $metaclass_name>
-
-This tells the class to use a custom attribute metaclass for this particular
-attribute. Custom attribute metaclasses are useful for extending the
-capabilities of the I<has> keyword: they are the simplest way to extend the MOP,
-but they are still a fairly advanced topic and too much to cover here. I will
-try and write a recipe on them soon.
-
-The default behavior here is to just load C<$metaclass_name>; however, we also
-have a way to alias to a shorter name. This will first look to see if
-B<Moose::Meta::Attribute::Custom::$metaclass_name> exists. If it does, Moose
-will then check to see if that has the method C<register_implementation>, which
-should return the actual name of the custom attribute metaclass. If there is no
-C<register_implementation> method, it will fall back to using
-B<Moose::Meta::Attribute::Custom::$metaclass_name> as the metaclass name.
-
 =item I<trigger =E<gt> $code>
 
 The I<trigger> option is a CODE reference which will be called after the value of
@@ -499,10 +492,6 @@ The I<handles> option provides Moose classes with automated delegation features.
 This is a pretty complex and powerful option. It accepts many different option
 formats, each with its own benefits and drawbacks.
 
-B<NOTE:> This feature is no longer experimental, but it may still have subtle
-bugs lurking in the deeper corners. If you think you have found a bug, you
-probably have, so please report it to me right away.
-
 B<NOTE:> The class being delegated to does not need to be a Moose based class,
 which is why this feature is especially useful when wrapping non-Moose classes.
 
@@ -602,6 +591,37 @@ a HASH ref) of the methods you want mapped.
 
 =back
 
+=item I<metaclass =E<gt> $metaclass_name>
+
+This tells the class to use a custom attribute metaclass for this particular
+attribute. Custom attribute metaclasses are useful for extending the
+capabilities of the I<has> keyword: they are the simplest way to extend the MOP,
+but they are still a fairly advanced topic and too much to cover here, see 
+L<Moose::Cookbook::Recipe11> for more information.
+
+The default behavior here is to just load C<$metaclass_name>; however, we also
+have a way to alias to a shorter name. This will first look to see if
+B<Moose::Meta::Attribute::Custom::$metaclass_name> exists. If it does, Moose
+will then check to see if that has the method C<register_implementation>, which
+should return the actual name of the custom attribute metaclass. If there is no
+C<register_implementation> method, it will fall back to using
+B<Moose::Meta::Attribute::Custom::$metaclass_name> as the metaclass name.
+
+=item I<traits =E<gt> [ @role_names ]>
+
+This tells Moose to take the list of C<@role_names> and apply them to the 
+attribute meta-object. This is very similar to the I<metaclass> option, but 
+allows you to use more than one extension at a time. This too is an advanced 
+topic, we don't yet have a cookbook for it though. 
+
+As with I<metaclass>, the default behavior is to just load C<$role_name>; however, 
+we also have a way to alias to a shorter name. This will first look to see if
+B<Moose::Meta::Attribute::Custom::Trait::$role_name> exists. If it does, Moose
+will then check to see if that has the method C<register_implementation>, which
+should return the actual name of the custom attribute trait. If there is no
+C<register_implementation> method, it will fall back to using
+B<Moose::Meta::Attribute::Custom::Trait::$metaclass_name> as the trait name.
+
 =back
 
 =item B<has +$name =E<gt> %options>
@@ -724,18 +744,18 @@ method call and the C<SUPER::> pseudo-package; it is really your choice.
 The keyword C<inner>, much like C<super>, is a no-op outside of the context of
 an C<augment> method. You can think of C<inner> as being the inverse of
 C<super>; the details of how C<inner> and C<augment> work is best described in
-the L<Moose::Cookbook>.
+the L<Moose::Cookbook::Recipe7>.
 
 =item B<augment ($name, &sub)>
 
 An C<augment> method, is a way of explicitly saying "I am augmenting this
 method from my superclass". Once again, the details of how C<inner> and
-C<augment> work is best described in the L<Moose::Cookbook>.
+C<augment> work is best described in the L<Moose::Cookbook::Recipe7>.
 
 =item B<confess>
 
 This is the C<Carp::confess> function, and exported here because I use it
-all the time. This feature may change in the future, so you have been warned.
+all the time. 
 
 =item B<blessed>
 
@@ -825,6 +845,13 @@ two features separate (yet interoperable) actually makes them easy to use, since
 their behavior is then easier to predict. Time will tell whether I am right or
 not (UPDATE: so far so good).
 
+=item *
+
+It is important to note that we currently have no simple way of combining 
+multiple extended versions of Moose (see L<EXTENDING AND EMBEDDING MOOSE> above), 
+and that in many cases they will conflict with one another. We are working on 
+developing a way around this issue, but in the meantime, you have been warned.
+
 =back
 
 =head1 ACKNOWLEDGEMENTS
@@ -870,6 +897,17 @@ technologies.
 
 =back
 
+=head2 Books
+
+=over 4
+
+=item The Art of the MetaObject Protocol
+
+I mention this in the L<Class::MOP> docs too, this book was critical in 
+the development of both modules and is highly recommended.
+
+=back
+
 =head2 Papers
 
 =over 4
diff --git a/lib/Moose/Cookbook/FAQ.pod b/lib/Moose/Cookbook/FAQ.pod
index ead3438..9f1092c 100644
--- a/lib/Moose/Cookbook/FAQ.pod
+++ b/lib/Moose/Cookbook/FAQ.pod
@@ -11,11 +11,11 @@ Moose::Cookbook::FAQ - Frequently asked questions about Moose
 
 =head3 Is Moose "production ready"?
 
-Yes. I have three medium-to-large-ish web applications in 
+Yes. I have several medium-to-large-ish web applications in 
 production using Moose, they have been running without 
-issue now for almost a year. 
+issue now for well over a year. 
 
-At $work we are re-writing our core offering to use Moose, 
+At C<$work> we are re-writing our core offering to use Moose, 
 so it's continued development is assured. 
 
 Several other people on #moose either have apps in production 
@@ -44,7 +44,7 @@ is mostly compile time. At this point we do have some options
 available for getting the speed you need. 
 
 Currently we have the option of making your classes immutable 
-as a means of boosting speed. This will mean a larger compile 
+as a means of boosting speed. This will mean a slightly larger compile 
 time cost, but the runtime speed increase (especially in object
 construction) is pretty significant. This is not very well 
 documented yet, so please ask on the list or on #moose for more
@@ -57,10 +57,7 @@ conversion to XS.
 
 =head3 When will Moose 1.0 be ready?
 
-It is right now, I just haven't bumped the version number up yet.
-
-I still have some more internal TODO items I would like to complete
-before I would even consider bumping it to 1.0.
+It is right now, I declared 0.18 to be "ready to use".
 
 =head2 Constructors
 
diff --git a/lib/Moose/Cookbook/Recipe7.pod b/lib/Moose/Cookbook/Recipe7.pod
index 49a0932..c54d39a 100644
--- a/lib/Moose/Cookbook/Recipe7.pod
+++ b/lib/Moose/Cookbook/Recipe7.pod
@@ -55,6 +55,8 @@ Moose::Cookbook::Recipe7 - The augment/inner example
   sub create_tps_report {
      (shift)->append_body('<report type="tps"/>') 
   }
+  
+  print TPSReport->new->create # <page><header/><report type="tps"/><footer/></page>
 
 =head1 DESCRIPTION
 
diff --git a/lib/Moose/Spec/Role.pod b/lib/Moose/Spec/Role.pod
index b44667a..7dbfcfe 100644
--- a/lib/Moose/Spec/Role.pod
+++ b/lib/Moose/Spec/Role.pod
@@ -7,6 +7,8 @@ Moose::Spec::Role - Formal spec for Role behavior
 
 =head1 DESCRIPTION
 
+B<NOTE:> This document is currently incomplete.
+
 =head2 Components of a Role
 
 =over 4
@@ -262,6 +264,25 @@ It is important to note that Role::FooBar is simply fufilling the
 required C<foo> method, and **NOT** overriding C<foo>. This is an 
 important distinction to make.
 
+Now here is another example of a (correct) type of overriding, this 
+time using the I<excludes> option.
+
+    package Role::Foo;
+    use Moose::Role;
+    
+    sub foo { ... }
+    
+    package Role::FooBar;
+    use Moose::Role;
+    
+    with 'Role::Foo' => { excludes => 'foo' };
+    
+    sub foo { ... }
+    sub bar { ... }
+
+By specifically excluding the C<foo> method during composition, 
+we allow B<Role::FooBar> to define it's own version of C<foo>.
+
 =back
 
 =head1 SEE ALSO
diff --git a/lib/Moose/Util.pm b/lib/Moose/Util.pm
index 5d1ba37..32cf5a9 100644
--- a/lib/Moose/Util.pm
+++ b/lib/Moose/Util.pm
@@ -144,11 +144,14 @@ Moose::Util - Utilities for working with Moose classes
 
 =head1 DESCRIPTION
 
-This is a set of utility functions to help working with Moose classes. This 
-is an experimental module, and it's not 100% clear what purpose it will serve. 
-That said, ideas, suggestions and contributions to this collection are most 
-welcome. See the L<TODO> section below for a list of ideas for possible 
-functions to write.
+This is a set of utility functions to help working with Moose classes, and 
+is used internally by Moose itself. The goal is to provide useful functions
+that for both Moose users and Moose extenders (MooseX:: authors).
+
+This is a relatively new addition to the Moose toolchest, so ideas, 
+suggestions and contributions to this collection are most welcome. 
+See the L<TODO> section below for a list of ideas for possible functions 
+to write.
 
 =head1 EXPORTED FUNCTIONS
 
diff --git a/lib/Moose/Util/TypeConstraints.pm b/lib/Moose/Util/TypeConstraints.pm
index b33c0f6..c79046e 100644
--- a/lib/Moose/Util/TypeConstraints.pm
+++ b/lib/Moose/Util/TypeConstraints.pm
@@ -632,11 +632,13 @@ and they are not used by Moose unless you tell it to. No type
 inference is performed, expression are not typed, etc. etc. etc.
 
 This is simply a means of creating small constraint functions which
-can be used to simplify your own type-checking code.
+can be used to simplify your own type-checking code, with the added 
+side benefit of making your intentions clearer through self-documentation.
 
 =head2 Slightly Less Important Caveat
 
-It is almost always a good idea to quote your type and subtype names.
+It is B<always> a good idea to quote your type and subtype names.
+
 This is to prevent perl from trying to execute the call as an indirect
 object call. This issue only seems to come up when you have a subtype
 the same name as a valid class, but when the issue does arise it tends
@@ -660,8 +662,8 @@ yet to have been created yet, is to simply do this:
 
 =head2 Default Type Constraints
 
-This module also provides a simple hierarchy for Perl 5 types, this
-could probably use some work, but it works for me at the moment.
+This module also provides a simple hierarchy for Perl 5 types, here is 
+that hierarchy represented visually.
 
   Any
   Item
@@ -685,8 +687,6 @@ could probably use some work, but it works for me at the moment.
               Object
                   Role
 
-Suggestions for improvement are welcome.
-
 B<NOTE:> Any type followed by a type parameter C<[`a]> can be
 parameterized, this means you can say:
 
@@ -703,12 +703,19 @@ existence check. This means that your class B<must> be loaded for
 this type constraint to pass. I know this is not ideal for all,
 but it is a saner restriction than most others.
 
+=head2 Type Constraint Naming 
+
+Since the types created by this module are global, it is suggested 
+that you namespace your types just as you would namespace your 
+modules. So instead of creating a I<Color> type for your B<My::Graphics>
+module, you would call the type I<My::Graphics::Color> instead.
+
 =head2 Use with Other Constraint Modules
 
 This module should play fairly nicely with other constraint
 modules with only some slight tweaking. The C<where> clause
 in types is expected to be a C<CODE> reference which checks
-it's first argument and returns a bool. Since most constraint
+it's first argument and returns a boolean. Since most constraint
 modules work in a similar way, it should be simple to adapt
 them to work with Moose.
 
@@ -720,7 +727,8 @@ L<Declare::Constraints::Simple> to declare a completely new type.
           -keys   => HasLength,
           -values => IsArrayRef( IsObject ));
 
-For more examples see the F<t/204_example_w_DCS.t> test file.
+For more examples see the F<t/200_examples/204_example_w_DCS.t> 
+test file.
 
 Here is an example of using L<Test::Deep> and it's non-test
 related C<eq_deeply> function.
@@ -734,87 +742,11 @@ related C<eq_deeply> function.
               })))
         };
 
-For a complete example see the F<t/205_example_w_TestDeep.t>
-test file.
+For a complete example see the 
+F<t/200_examples/205_example_w_TestDeep.t> test file.
 
 =head1 FUNCTIONS
 
-=head2 Type Constraint Construction & Locating
-
-=over 4
-
-=item B<create_type_constraint_union ($pipe_seperated_types | @type_constraint_names)>
-
-Given string with C<$pipe_seperated_types> or a list of C<@type_constraint_names>,
-this will return a L<Moose::Meta::TypeConstraint::Union> instance.
-
-=item B<create_parameterized_type_constraint ($type_name)>
-
-Given a C<$type_name> in the form of:
-
-  BaseType[ContainerType]
-
-this will extract the base type and container type and build an instance of
-L<Moose::Meta::TypeConstraint::Parameterized> for it.
-
-=item B<create_class_type_constraint ($class, ?$message)>
-
-Given a class name it will create a new L<Moose::Meta::TypeConstraint::Class>
-object for that class name.
-
-=item B<find_or_create_type_constraint ($type_name, ?$options_for_anon_type)>
-
-This will attempt to find or create a type constraint given the a C<$type_name>.
-If it cannot find it in the registry, it will see if it should be a union or
-container type an create one if appropriate, and lastly if nothing can be
-found or created that way, it will create an anon-type using the
-C<$options_for_anon_type> HASH ref to populate it. If the C<$options_for_anon_type>
-is not specified (it is C<undef>), then it will not create anything and simply
-return.
-
-=item B<find_type_constraint ($type_name)>
-
-This function can be used to locate a specific type constraint
-meta-object, of the class L<Moose::Meta::TypeConstraint> or a
-derivative. What you do with it from there is up to you :)
-
-=item B<register_type_constraint ($type_object)>
-
-This function will register a named type constraint with the type registry.
-
-=item B<get_type_constraint_registry>
-
-Fetch the L<Moose::Meta::TypeConstraint::Registry> object which
-keeps track of all type constraints.
-
-=item B<list_all_type_constraints>
-
-This will return a list of type constraint names, you can then
-fetch them using C<find_type_constraint ($type_name)> if you
-want to.
-
-=item B<list_all_builtin_type_constraints>
-
-This will return a list of builtin type constraints, meaning,
-those which are defined in this module. See the section
-labeled L<Default Type Constraints> for a complete list.
-
-=item B<export_type_constraints_as_functions>
-
-This will export all the current type constraints as functions
-into the caller's namespace. Right now, this is mostly used for
-testing, but it might prove useful to others.
-
-=item B<get_all_parameterizable_types>
-
-This returns all the parameterizable types that have been registered.
-
-=item B<add_parameterizable_type ($type)>
-
-Adds C<$type> to the list of parameterizable types
-
-=back
-
 =head2 Type Constraint Constructors
 
 The following functions are used to create type constraints.
@@ -913,6 +845,82 @@ This is just sugar for the type coercion construction syntax.
 
 =back
 
+=head2 Type Constraint Construction & Locating
+
+=over 4
+
+=item B<create_type_constraint_union ($pipe_seperated_types | @type_constraint_names)>
+
+Given string with C<$pipe_seperated_types> or a list of C<@type_constraint_names>,
+this will return a L<Moose::Meta::TypeConstraint::Union> instance.
+
+=item B<create_parameterized_type_constraint ($type_name)>
+
+Given a C<$type_name> in the form of:
+
+  BaseType[ContainerType]
+
+this will extract the base type and container type and build an instance of
+L<Moose::Meta::TypeConstraint::Parameterized> for it.
+
+=item B<create_class_type_constraint ($class, ?$message)>
+
+Given a class name it will create a new L<Moose::Meta::TypeConstraint::Class>
+object for that class name.
+
+=item B<find_or_create_type_constraint ($type_name, ?$options_for_anon_type)>
+
+This will attempt to find or create a type constraint given the a C<$type_name>.
+If it cannot find it in the registry, it will see if it should be a union or
+container type an create one if appropriate, and lastly if nothing can be
+found or created that way, it will create an anon-type using the
+C<$options_for_anon_type> HASH ref to populate it. If the C<$options_for_anon_type>
+is not specified (it is C<undef>), then it will not create anything and simply
+return.
+
+=item B<find_type_constraint ($type_name)>
+
+This function can be used to locate a specific type constraint
+meta-object, of the class L<Moose::Meta::TypeConstraint> or a
+derivative. What you do with it from there is up to you :)
+
+=item B<register_type_constraint ($type_object)>
+
+This function will register a named type constraint with the type registry.
+
+=item B<get_type_constraint_registry>
+
+Fetch the L<Moose::Meta::TypeConstraint::Registry> object which
+keeps track of all type constraints.
+
+=item B<list_all_type_constraints>
+
+This will return a list of type constraint names, you can then
+fetch them using C<find_type_constraint ($type_name)> if you
+want to.
+
+=item B<list_all_builtin_type_constraints>
+
+This will return a list of builtin type constraints, meaning,
+those which are defined in this module. See the section
+labeled L<Default Type Constraints> for a complete list.
+
+=item B<export_type_constraints_as_functions>
+
+This will export all the current type constraints as functions
+into the caller's namespace. Right now, this is mostly used for
+testing, but it might prove useful to others.
+
+=item B<get_all_parameterizable_types>
+
+This returns all the parameterizable types that have been registered.
+
+=item B<add_parameterizable_type ($type)>
+
+Adds C<$type> to the list of parameterizable types
+
+=back
+
 =head2 Namespace Management
 
 =over 4
diff --git a/lib/Moose/Util/TypeConstraints/OptimizedConstraints.pm b/lib/Moose/Util/TypeConstraints/OptimizedConstraints.pm
index f40845c..3ad1f88 100644
--- a/lib/Moose/Util/TypeConstraints/OptimizedConstraints.pm
+++ b/lib/Moose/Util/TypeConstraints/OptimizedConstraints.pm
@@ -52,7 +52,8 @@ bodies for various moose types
 
 =head1 DESCRIPTION
 
-This file contains the hand optimized versions of Moose type constraints.
+This file contains the hand optimized versions of Moose type constraints, 
+no user serviceable parts inside.
 
 =head1 FUNCTIONS
 
@@ -100,7 +101,7 @@ Yuval Kogman E<lt>nothingmuch@cpan.orgE<gt>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2006-2008 by Infinity Interactive, Inc.
+Copyright 2007-2008 by Infinity Interactive, Inc.
 
 L<http://www.iinteractive.com>
 
diff --git a/lib/Test/Moose.pm b/lib/Test/Moose.pm
index 3228213..bf96c27 100644
--- a/lib/Test/Moose.pm
+++ b/lib/Test/Moose.pm
@@ -5,6 +5,7 @@ use warnings;
 
 use Sub::Exporter;
 use Test::Builder;
+
 use Moose::Util 'does_role', 'find_meta';
 
 our $VERSION   = '0.01';
@@ -156,7 +157,7 @@ Stevan Little E<lt>stevan@iinteractive.comE<gt>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2007 by Infinity Interactive, Inc.
+Copyright 2007-2008 by Infinity Interactive, Inc.
 
 L<http://www.iinteractive.com>
 
diff --git a/lib/oose.pm b/lib/oose.pm
index b54e591..e7cc8d0 100644
--- a/lib/oose.pm
+++ b/lib/oose.pm
@@ -1,4 +1,5 @@
 package oose;
+
 use strict;
 use warnings;