From: Stevan Little <stevan.little@iinteractive.com>
Date: Fri, 8 Feb 2008 22:49:11 +0000 (+0000)
Subject: bunch of doc fixes
X-Git-Tag: 0_53~1
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=127d39a79d936afd136ccfd8ff8271eea2bc0cbb;p=gitmo%2FClass-MOP.git

bunch of doc fixes
---

diff --git a/Changes b/Changes
index 9db7dc3..79a1952 100644
--- a/Changes
+++ b/Changes
@@ -1,6 +1,8 @@
 Revision history for Perl extension Class-MOP.
 
 0.53
+    ~~~ some misc. doc. fixes ~~~
+    
     * Class::MOP::Instance
       - added get_all_slot_values method (Sartak)
         - added tests for this (Sartak)
diff --git a/lib/Class/MOP.pm b/lib/Class/MOP.pm
index be88dc7..f5db6bd 100644
--- a/lib/Class/MOP.pm
+++ b/lib/Class/MOP.pm
@@ -566,7 +566,7 @@ Class::MOP - A Meta Object Protocol for Perl 5
 
 =head1 DESCRIPTON
 
-This module is an attempt to create a meta object protocol for the
+This module is a fully functioning meta object protocol for the
 Perl 5 object system. It makes no attempt to change the behavior or
 characteristics of the Perl 5 object system, only to create a
 protocol for its manipulation and introspection.
@@ -694,7 +694,7 @@ programming. So in other words, don't worry about it.
 
 =head1 PROTOCOLS
 
-The protocol is divided into 3 main sub-protocols:
+The protocol is divided into 4 main sub-protocols:
 
 =over 4
 
@@ -710,7 +710,7 @@ See L<Class::MOP::Class> for more details.
 
 This provides a consistent represenation for an attribute of a
 Perl 5 class. Since there are so many ways to create and handle
-atttributes in Perl 5 OO, this attempts to provide as much of a
+attributes in Perl 5 OO, this attempts to provide as much of a
 unified approach as possible, while giving the freedom and
 flexibility to subclass for specialization.
 
@@ -725,6 +725,16 @@ making it possible to extend the system in many ways.
 
 See L<Class::MOP::Method> for more details.
 
+=item The Instance protocol
+
+This provides a layer of abstraction for creating object instances. 
+Since the other layers use this protocol, it is relatively easy to 
+change the type of your instances from the default HASH ref to other
+types of references. Several examples are provided in the F<examples/> 
+directory included in this distribution.
+
+See L<Class::MOP::Instance> for more details.
+
 =back
 
 =head1 FUNCTIONS
@@ -749,6 +759,8 @@ compat.
 
 This will load a given C<$class_name> and if it does not have an
 already initialized metaclass, then it will intialize one for it.
+This function can be used in place of tricks like 
+C<eval "use $module"> or using C<require>.
 
 =item B<is_class_loaded ($class_name)>
 
@@ -761,8 +773,19 @@ is probably correct about 99% of the time.
 
 =item B<check_package_cache_flag ($pkg)>
 
+This will return an integer that is managed by C<Class::MOP::Class>
+to determine if a module's symbol table has been altered. 
+
+In Perl 5.10 or greater, this flag is package specific. However in 
+versions prior to 5.10, this will use the C<PL_sub_generation> variable
+which is not package specific. 
+
 =item B<get_code_info ($code)>
 
+This function returns two values, the name of the package the C<$code> 
+is from and the name of the C<$code> itself. This is used by several 
+elements of the MOP to detemine where a given C<$code> reference is from.
+
 =back
 
 =head2 Metaclass cache functions
@@ -791,14 +814,28 @@ been cached by B<Class::MOP::Class>.
 
 =item B<get_metaclass_by_name ($name)>
 
+This will return a cached B<Class::MOP::Class> instance of nothing
+if no metaclass exist by that C<$name>.
+
 =item B<store_metaclass_by_name ($name, $meta)>
 
+This will store a metaclass in the cache at the supplied C<$key>.
+
 =item B<weaken_metaclass ($name)>
 
+In rare cases it is desireable to store a weakened reference in 
+the metaclass cache. This function will weaken the reference to 
+the metaclass stored in C<$name>.
+
 =item B<does_metaclass_exist ($name)>
 
+This will return true of there exists a metaclass stored in the 
+C<$name> key and return false otherwise.
+
 =item B<remove_metaclass_by_name ($name)>
 
+This will remove a the metaclass stored in the C<$name> key.
+
 =back
 
 =head1 SEE ALSO
diff --git a/lib/Class/MOP/Attribute.pm b/lib/Class/MOP/Attribute.pm
index 82f0d6e..5d4994c 100644
--- a/lib/Class/MOP/Attribute.pm
+++ b/lib/Class/MOP/Attribute.pm
@@ -487,7 +487,7 @@ so:
 And lastly, if the value of your attribute is dependent upon
 some other aspect of the instance structure, then you can take
 advantage of the fact that when the I<default> value is a CODE
-reference, it is passed the raw (unblessed) instance structure
+reference, it is passed the (as yet unfinished) instance structure
 as it's only argument. So you can do things like this:
 
   Class::MOP::Attribute->new('$object_identity' => (
@@ -511,9 +511,6 @@ slot-setting CODE ref, and the attribute meta-instance.  The slot-setting code
 is provided to make it easy to set the (possibly altered) value on the instance
 without going through several more method calls.
 
-If no initializer is given (as is the common case) initial attribute values are
-set directly, bypassing the writer.
-
 This contrived example shows an initializer that sets the attribute to twice
 the given value.
 
@@ -532,6 +529,9 @@ attribute initialization use the writer:
       initializer => 'some_attr',
   ));
 
+Your writer will simply need to examine it's C<@_> and determine under
+which context it is being called.
+
 =back
 
 The I<accessor>, I<reader>, I<writer>, I<predicate> and I<clearer> keys can
@@ -597,8 +597,15 @@ back to their "unfulfilled" state.
 
 =item B<clone (%options)>
 
+This will return a clone of the attribute instance, allowing the overriding
+of various attributes through the C<%options> supplied.
+
 =item B<initialize_instance_slot ($instance, $params)>
 
+This method is used internally to initialize the approriate slot for this 
+attribute in a given C<$instance>, the C<$params> passed are those that were
+passed to the constructor.
+
 =back
 
 =head2 Value management
@@ -693,7 +700,7 @@ Return the CODE reference of a method suitable for reading / writing the
 value of the attribute in the associated class. Suitable for use whether 
 C<reader> and C<writer> or C<accessor> was specified or not.
 
-NOTE: If not reader/writer/accessor was specified, this will use the 
+NOTE: If no reader/writer/accessor was specified, this will use the 
 attribute get_value/set_value methods, which can be very inefficient.
 
 =back
@@ -772,7 +779,8 @@ used internally by the accessor generator.
 =item B<associated_methods>
 
 This will return the list of methods which have been associated with
-the C<associate_method> methods.
+the C<associate_method> methods. This is a good way of seeing what 
+methods are used to manage a given attribute. 
 
 =item B<install_accessors>
 
@@ -813,7 +821,7 @@ to this class.
 
 It should also be noted that B<Class::MOP> will actually bootstrap
 this module by installing a number of attribute meta-objects into
-it's metaclass. This will allow this class to reap all the benifits
+it's metaclass. This will allow this class to reap all the benefits
 of the MOP when subclassing it.
 
 =back
diff --git a/lib/Class/MOP/Class.pm b/lib/Class/MOP/Class.pm
index 06d6fcb..127b360 100644
--- a/lib/Class/MOP/Class.pm
+++ b/lib/Class/MOP/Class.pm
@@ -433,27 +433,6 @@ sub rebless_instance {
     }
 }
 
-sub get_attribute_values {
-    my ($self, $instance) = @_;
-
-    return +{
-        map { $_->name => $_->get_value($instance) }
-            grep { $_->has_value($instance) }
-                $self->compute_all_applicable_attributes
-    };
-}
-
-sub get_init_args {
-    my ($self, $instance) = @_;
-
-    return +{
-        map { $_->init_arg => $_->get_value($instance) }
-            grep { $_->has_value($instance) }
-                grep { defined($_->init_arg) } 
-                    $self->compute_all_applicable_attributes
-    };
-}
-
 # Inheritance
 
 sub superclasses {
@@ -1070,7 +1049,8 @@ but in some cases you might want to use it, so it is here.
 
 =item B<reset_package_cache_flag>
 
-Clear this flag, used in Moose.
+Clears the package cache flag to announce to the internals that we need 
+to rebuild the method map.
 
 =back
 
@@ -1083,8 +1063,14 @@ to use them or not.
 
 =item B<instance_metaclass>
 
+Returns the class name of the instance metaclass, see L<Class::MOP::Instance> 
+for more information on the instance metaclasses.
+
 =item B<get_meta_instance>
 
+Returns an instance of L<Class::MOP::Instance> to be used in the construction 
+of a new instance of the class. 
+
 =item B<new_object (%params)>
 
 This is a convience method for creating a new object of the class, and
@@ -1096,12 +1082,9 @@ would call a C<new> this method like so:
       $class->meta->new_object(%params);
   }
 
-Of course the ideal place for this would actually be in C<UNIVERSAL::>
-but that is considered bad style, so we do not do that.
-
 =item B<construct_instance (%params)>
 
-This method is used to construct an instace structure suitable for
+This method is used to construct an instance structure suitable for
 C<bless>-ing into your package of choice. It works in conjunction
 with the Attribute protocol to collect all applicable attributes.
 
@@ -1125,9 +1108,6 @@ class would call a C<clone> this method like so:
       $self->meta->clone_object($self, %params);
   }
 
-Of course the ideal place for this would actually be in C<UNIVERSAL::>
-but that is considered bad style, so we do not do that.
-
 =item B<clone_instance($instance, %params)>
 
 This method is a compliment of C<construct_instance> (which means if
@@ -1146,24 +1126,11 @@ shallow cloning is outside the scope of the meta-object protocol. I
 think Yuval "nothingmuch" Kogman put it best when he said that cloning
 is too I<context-specific> to be part of the MOP.
 
-=item B<get_attribute_values($instance)>
-
-Returns the values of the C<$instance>'s fields keyed by the attribute names.
-
-=item B<get_init_args($instance)>
-
-Returns a hash reference where the keys are all the attributes' C<init_arg>s
-and the values are the instance's fields. Attributes without an C<init_arg>
-will be skipped.
-
 =item B<rebless_instance($instance)>
 
 This will change the class of C<$instance> to the class of the invoking
 C<Class::MOP::Class>. You may only rebless the instance to a subclass of
-itself. This limitation may be relaxed in the future.
-
-This can be useful in a number of situations, such as when you are writing
-a program that doesn't know everything at object construction time.
+itself. 
 
 =back
 
@@ -1197,18 +1164,11 @@ This is a read-write attribute which represents the superclass
 relationships of the class the B<Class::MOP::Class> instance is
 associated with. Basically, it can get and set the C<@ISA> for you.
 
-B<NOTE:>
-Perl will occasionally perform some C<@ISA> and method caching, if
-you decide to change your superclass relationship at runtime (which
-is quite insane and very much not recommened), then you should be
-aware of this and the fact that this module does not make any
-attempt to address this issue.
-
 =item B<class_precedence_list>
 
 This computes the a list of all the class's ancestors in the same order
-in which method dispatch will be done. This is similair to
-what B<Class::ISA::super_path> does, but we don't remove duplicate names.
+in which method dispatch will be done. This is similair to what 
+B<Class::ISA::super_path> does, but we don't remove duplicate names.
 
 =item B<linearized_isa>
 
@@ -1217,7 +1177,7 @@ duplicates removed.
 
 =item B<subclasses>
 
-This returns a list of subclasses for this class.
+This returns a list of subclasses for this class. 
 
 =back
 
@@ -1227,8 +1187,13 @@ This returns a list of subclasses for this class.
 
 =item B<get_method_map>
 
+Returns a HASH ref of name to CODE reference mapping for this class.
+
 =item B<method_metaclass>
 
+Returns the class name of the method metaclass, see L<Class::MOP::Method> 
+for more information on the method metaclasses.
+
 =item B<add_method ($method_name, $method)>
 
 This will take a C<$method_name> and CODE reference to that
@@ -1441,9 +1406,14 @@ their own. See L<Class::MOP::Attribute> for more details.
 
 =item B<attribute_metaclass>
 
+Returns the class name of the attribute metaclass, see L<Class::MOP::Attribute> 
+for more information on the attribute metaclasses.
+
 =item B<get_attribute_map>
 
-=item B<add_attribute ($attribute_meta_object | $attribute_name, %attribute_spec)>
+This returns a HASH ref of name to attribute meta-object mapping.
+
+=item B<add_attribute ($attribute_meta_object | ($attribute_name, %attribute_spec))>
 
 This stores the C<$attribute_meta_object> (or creates one from the
 C<$attribute_name> and C<%attribute_spec>) in the B<Class::MOP::Class>
diff --git a/lib/Class/MOP/Immutable.pm b/lib/Class/MOP/Immutable.pm
index aabb62b..2b4e0d3 100644
--- a/lib/Class/MOP/Immutable.pm
+++ b/lib/Class/MOP/Immutable.pm
@@ -53,7 +53,7 @@ my %DEFAULT_METHODS = (
     meta => sub {
         my $self = shift;
         # if it is not blessed, then someone is asking
-        # for the meta of Class::MOP::Class::Immutable
+        # for the meta of Class::MOP::Immutable
         return Class::MOP::Class->initialize($self) unless blessed($self);
         # otherwise, they are asking for the metaclass
         # which has been made immutable, which is itself
@@ -281,8 +281,9 @@ metaclass. Current features include making methods read-only,
 making methods un-callable and memoizing methods (in a type specific
 way too).
 
-This module is fairly new to the MOP, and quite possibly will be
-expanded and further generalized as the need arises.
+This module is not for the feint of heart, it does some whacky things
+to the metaclass in order to make it immutable. If you are just curious, 
+I suggest you turn back now, there is nothing to see here.
 
 =head1 METHODS
 
diff --git a/lib/Class/MOP/Instance.pm b/lib/Class/MOP/Instance.pm
index a9d5a5d..90bddbc 100644
--- a/lib/Class/MOP/Instance.pm
+++ b/lib/Class/MOP/Instance.pm
@@ -180,12 +180,6 @@ __END__
 
 Class::MOP::Instance - Instance Meta Object
 
-=head1 SYNOPSIS
-
-    # This API is largely internal
-    # you shouldn't need it unless you are writing meta attributes or meta
-    # instances
-
 =head1 DESCRIPTION
 
 The meta instance is used by attributes for low level storage.
@@ -235,6 +229,8 @@ This does just exactly what it says it does.
 
 =item B<clone_instance ($instance_structure)>
 
+This too does just exactly what it says it does.
+
 =back
 
 =head2 Instrospection
@@ -246,6 +242,8 @@ we will add then when we need them basically.
 
 =item B<associated_metaclass>
 
+This returns the metaclass associated with this instance.
+
 =item B<get_all_slots>
 
 This will return the current list of slots based on what was
@@ -253,6 +251,8 @@ given to this object in C<new>.
 
 =item B<is_valid_slot ($slot_name)>
 
+This will return true if C<$slot_name> is a valid slot name.
+
 =back
 
 =head2 Operations on Instance Structures
@@ -262,6 +262,10 @@ instance meta-object is a different entity from the actual
 instance it creates. For this reason, any actions on slots
 require that the C<$instance_structure> is passed into them.
 
+The names of these methods pretty much explain exactly 
+what they do, if that is not enough then I suggest reading 
+the source, it is very straightfoward.
+
 =over 4
 
 =item B<get_slot_value ($instance_structure, $slot_name)>
@@ -288,19 +292,13 @@ require that the C<$instance_structure> is passed into them.
 
 =head2 Inlineable Instance Operations
 
-This part of the API is currently un-used. It is there for use
-in future experiments in class finailization mostly. Best to
-ignore this for now.
-
 =over 4
 
 =item B<is_inlinable>
 
 Each meta-instance should override this method to tell Class::MOP if it's
-possible to inline the slot access.
-
-This is currently only used by Class::MOP::Class::Immutable when performing
-optimizations.
+possible to inline the slot access. This is currently only used by 
+L<Class::MOP::Immutable> when performing optimizations.
 
 =item B<inline_create_instance>
 
diff --git a/lib/Class/MOP/Method.pm b/lib/Class/MOP/Method.pm
index 6878ba7..56b3037 100644
--- a/lib/Class/MOP/Method.pm
+++ b/lib/Class/MOP/Method.pm
@@ -80,10 +80,6 @@ __END__
 
 Class::MOP::Method - Method Meta Object
 
-=head1 SYNOPSIS
-
-  # ... more to come later maybe
-
 =head1 DESCRIPTION
 
 The Method Protocol is very small, since methods in Perl 5 are just 
@@ -107,7 +103,10 @@ to this class.
 
 =over 4
 
-=item B<wrap (&code)>
+=item B<wrap ($code)>
+
+This is the basic constructor, it returns a B<Class::MOP::Method> 
+instance which wraps the given C<$code> reference.
 
 =back
 
@@ -117,12 +116,20 @@ to this class.
 
 =item B<body>
 
+This returns the actual CODE reference of the particular instance.
+
 =item B<name>
 
+This returns the name of the CODE reference.
+
 =item B<package_name>
 
+This returns the package name that the CODE reference is attached to.
+
 =item B<fully_qualified_name>
 
+This returns the fully qualified name of the CODE reference.
+
 =back
 
 =head1 AUTHORS
diff --git a/lib/Class/MOP/Method/Constructor.pm b/lib/Class/MOP/Method/Constructor.pm
index a8d18b7..9ac824d 100644
--- a/lib/Class/MOP/Method/Constructor.pm
+++ b/lib/Class/MOP/Method/Constructor.pm
@@ -182,7 +182,8 @@ Class::MOP::Method::Constructor - Method Meta Object for constructors
 =head1 DESCRIPTION
 
 This is a subclass of C<Class::MOP::Method> which deals with
-class constructors.
+class constructors. This is used when making a class immutable
+to generate an optimized constructor.
 
 =head1 METHODS
 
@@ -219,7 +220,7 @@ This creates the code reference for the constructor itself.
 
 =back
 
-=head2 Method Generators
+=head2 Method Generators 
 
 =over 4
 
diff --git a/lib/Class/MOP/Method/Wrapped.pm b/lib/Class/MOP/Method/Wrapped.pm
index 0055265..c32b506 100644
--- a/lib/Class/MOP/Method/Wrapped.pm
+++ b/lib/Class/MOP/Method/Wrapped.pm
@@ -145,26 +145,35 @@ __END__
 
 Class::MOP::Method::Wrapped - Method Meta Object to handle before/around/after modifiers
 
-=head1 SYNOPSIS
-
-  # ... more to come later maybe
-
 =head1 DESCRIPTION
 
+This is a L<Class::MOP::Method> subclass which provides the funtionality 
+to wrap a given CODE reference with before, after and around method modifiers.
+
 =head1 METHODS
 
 =head2 Construction
 
 =over 4
 
-=item B<wrap (&code)>
+=item B<wrap ($code)>
+
+This is the constructor, it will return a B<Class::MOP::Method::Wrapped>
+instance that can be used to add before, after and around modifiers to.
 
 =item B<get_original_method>
 
+This returns the original CODE reference that was provided to the 
+constructor.
+
 =back
 
 =head2 Modifiers
 
+These three methods will add the method modifiers to the wrapped 
+CODE reference. For more information on how method modifiers work, 
+see the section in L<Class::MOP::Class>.
+
 =over 4
 
 =item B<add_before_modifier ($code)>
diff --git a/lib/Class/MOP/Module.pm b/lib/Class/MOP/Module.pm
index 2a743a0..8c9fccd 100644
--- a/lib/Class/MOP/Module.pm
+++ b/lib/Class/MOP/Module.pm
@@ -47,16 +47,25 @@ __END__
 
 Class::MOP::Module - Module Meta Object
 
-=head1 SYNOPSIS
-
 =head1 DESCRIPTION
 
+This is an abstraction of a Perl 5 module, it is a superclass of
+L<Class::MOP::Class>. A module essentially a package with metadata, 
+in our case the version and authority. 
+
 =head1 METHODS
 
 =over 4
 
 =item B<meta>
 
+Returns a metaclass for this package.
+
+=item B<initialize ($package_name)>
+
+This will initialize a Class::MOP::Module instance which represents 
+the module of C<$package_name>.
+
 =item B<version>
 
 This is a read-only attribute which returns the C<$VERSION> of the 
diff --git a/lib/Class/MOP/Package.pm b/lib/Class/MOP/Package.pm
index d403f20..0e09c7f 100644
--- a/lib/Class/MOP/Package.pm
+++ b/lib/Class/MOP/Package.pm
@@ -226,18 +226,25 @@ __END__
 
 Class::MOP::Package - Package Meta Object
 
-=head1 SYNOPSIS
-
 =head1 DESCRIPTION
 
+This is an abstraction of a Perl 5 package, it is a superclass of
+L<Class::MOP::Class> and provides all of the symbol table 
+introspection methods.
+
 =head1 METHODS
 
 =over 4
 
 =item B<meta>
 
+Returns a metaclass for this package.
+
 =item B<initialize ($package_name)>
 
+This will initialize a Class::MOP::Package instance which represents 
+the package of C<$package_name>.
+
 =item B<name>
 
 This is a read-only attribute which returns the package name for the