X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FClass%2FMOP%2FAttribute.pm;h=941f90a4cc7b4450f2b931566b1933a9860ffaef;hb=2367814a108bbb85efbf76b57fc58bf464d68455;hp=2935d35c547bcd2e376fa7865f69f154f980dbbe;hpb=8ea9d56063946421d3a822fcd539620b42f34537;p=gitmo%2FClass-MOP.git

diff --git a/lib/Class/MOP/Attribute.pm b/lib/Class/MOP/Attribute.pm
index 2935d35..941f90a 100644
--- a/lib/Class/MOP/Attribute.pm
+++ b/lib/Class/MOP/Attribute.pm
@@ -262,6 +262,11 @@ sub install_accessors {
     
     sub remove_accessors {
         my $self = shift;
+        # TODO:
+        # we really need to make sure to remove from the 
+        # associates methods here as well. But this is 
+        # such a slimly used method, I am not worried 
+        # about it right now.
         $_remove_accessor->($self->accessor(),  $self->associated_class()) if $self->has_accessor();
         $_remove_accessor->($self->reader(),    $self->associated_class()) if $self->has_reader();
         $_remove_accessor->($self->writer(),    $self->associated_class()) if $self->has_writer();
@@ -445,6 +450,12 @@ back to their "unfulfilled" state.
 
 =head2 Value management
 
+These methods are basically "backdoors" to the instance, which can be used 
+to bypass the regular accessors, but still stay within the context of the MOP. 
+
+These methods are not for general use, and should only be used if you really 
+know what you are doing.
+
 =over 4
 
 =item B<set_value ($instance, $value)>
@@ -459,8 +470,15 @@ even to attributes with just write only accessors.
 
 =item B<has_value ($instance)>
 
+Returns a boolean indicating if the item in the C<$instance> has a value in it. 
+This is basically what the default C<predicate> method calls.
+
 =item B<clear_value ($instance)>
 
+This will clear the value in the C<$instance>. This is basically what the default
+C<clearer> would call. Note that this may be done even if the attirbute does not 
+have any associated read, write or clear methods.
+
 =back
 
 =head2 Informational
@@ -523,14 +541,32 @@ These are all basic predicate methods for the values passed into C<new>.
 
 =head2 Class association
 
+These methods allow you to manage the attributes association with 
+the class that contains it. These methods should not be used 
+lightly, nor are they very magical, they are mostly used internally
+and by metaclass instances.
+
 =over 4
 
 =item B<associated_class>
 
+This returns the metaclass this attribute is associated with.
+
 =item B<attach_to_class ($class)>
 
+This will store a weaken reference to C<$class> internally. You should 
+note that just changing the class assocation will not remove the attribute
+from it's old class, and initialize it (and it's accessors) in the new
+C<$class>. It is up to you to do this manually.
+
 =item B<detach_from_class>
 
+This will remove the weakened reference to the class. It does B<not> 
+remove the attribute itself from the class (or remove it's accessors), 
+you must do that yourself if you want too. Actually if that is what 
+you want to do, you should probably be looking at 
+L<Class::MOP::Class::remove_attribute> instead.
+
 =back
 
 =head2 Attribute Accessor generation
@@ -539,10 +575,20 @@ These are all basic predicate methods for the values passed into C<new>.
 
 =item B<accessor_metaclass>
 
-=item B<associate_method>
+Accessors are generated by an accessor metaclass, which is usually
+a subclass of C<Class::MOP::Method::Accessor>. This method returns 
+the name of the accessor metaclass that this attribute uses.
+
+=item B<associate_method ($method)>
+
+This will associate a C<$method> with the given attribute which is 
+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. 
+
 =item B<install_accessors>
 
 This allows the attribute to generate and install code for it's own 
@@ -566,6 +612,9 @@ This allows the attribute to remove the method for it's own
 I<accessor/reader/writer/predicate/clearer>. This is called by 
 C<Class::MOP::Class::remove_attribute>.
 
+NOTE: This does not currently remove methods from the list returned 
+by C<associated_methods>, that is on the TODO list.
+
 =back
 
 =head2 Introspection
@@ -592,7 +641,7 @@ Yuval Kogman E<lt>nothingmuch@woobling.comE<gt>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2006 by Infinity Interactive, Inc.
+Copyright 2006, 2007 by Infinity Interactive, Inc.
 
 L<http://www.iinteractive.com>