2 files changed, 186 insertions, 37 deletions
diff --git a/lib/Data/MultiValued/AttributeAccessors.pm b/lib/Data/MultiValued/AttributeAccessors.pm
index 63e9281..b5f0d65 100644
--- a/lib/Data/MultiValued/AttributeAccessors.pm
+++ b/lib/Data/MultiValued/AttributeAccessors.pm
@@ -134,10 +134,39 @@ version 0.0.1_3
 
 =head1 DESCRIPTION
 
-Subclass of L<Moose::Meta::Method::Accessor>, generates non-inlined
-(patches welcome) accessors for multi-valued attributes.
+=head2 C<_instance_is_inlinable>
+
+Returns C<0> to prevent attempts to inline the accessor methods.
+
+=head2 C<_generate_accessor_method>
+
+=head2 C<_generate_reader_method>
+
+=head2 C<_generate_writer_method>
+
+=head2 C<_generate_predicate_method>
+
+=head2 C<_generate_clearer_method>
+
+Delegate to C<set_multi_value>, C<get_multi_value>,
+C<has_multi_value>, C<clear_multi_value>, passing empty options
+(i.e. no tags, no ranges).
+
+=head2 C<_generate_multi_accessor_method>
+
+=head2 C<_generate_multi_reader_method>
+
+=head2 C<_generate_multi_writer_method>
+
+=head2 C<_generate_multi_predicate_method>
+
+=head2 C<_generate_multi_clearer_method>
+
+Delegate to C<set_multi_value>, C<get_multi_value>,
+C<has_multi_value>, C<clear_multi_value>, passing C<$_[1]> as options
+and C<$_[2]> as values.
 
-=head1 METHODS
+=head1 DESCRIPTION
 
 =head2 C<_instance_is_inlinable>
 
diff --git a/lib/Data/MultiValued/AttributeTrait.pm b/lib/Data/MultiValued/AttributeTrait.pm
index 322feb2..d24c6d9 100644
--- a/lib/Data/MultiValued/AttributeTrait.pm
+++ b/lib/Data/MultiValued/AttributeTrait.pm
@@ -291,47 +291,119 @@ version 0.0.1_3
 
 =head1 DESCRIPTION
 
-Don't use this role directly, use
-L<Data::MultiValued::AttributeTrait::Tags>,
-L<Data::MultiValued::AttributeTrait::Ranges> or
-L<Data::MultiValued::AttributeTrait::TagsAndRanges>.
+=head2 C<slots>
 
-This role (together with L<Data::MultiValued::AttributeAccessors>)
-defines all the basic plumbing to glue C<Data::MultiValued::Tags> etc
-into Moose attributes.
+Adds the L</full_storage_slot> to the list of used slots.
 
-=head1 ATTRIBUTES
+=head2 C<set_full_storage>
 
-=head2 C<full_storage_slot>
+Stores a new instance of L</multivalue_storage_class> into the
+L</full_storage_slot> of the instance.
 
-The instance slot to use to store the C<Data::MultiValued::Tags> or
-similar object. Defaults to C<"${name}__MULTIVALUED_STORAGE__">, where
-C<$name> is the attribute name.
+=head2 C<get_full_storage>
 
-=head2 C<multi_accessor>
+Retrieves the value of the L</full_storage_slot> of the instance.
 
-=head2 C<multi_reader>
+=head2 C<full_storage>
 
-=head2 C<multi_writer>
+Returns an instance of L</multivalue_storage_class>, either by
+retrieving it from the instance, or by creating one (and setting it in
+the instance). Calls L</get_full_storage> and L</set_full_storage>.
 
-=head2 C<multi_predicate>
+=head2 C<accessor_metaclass>
 
-=head2 C<multi_clearer>
+Makes sure that all accessors for this attribute are created via the
+L<Data::MultiValued::AttributeAccessors> method meta class.
 
-The names to use for the various additional accessors. See
-L<Class::MOP::Attribute> for details. These default to
-C<"${name}_multi"> where C<$name> is the name of the corresponding
-non-multi accessor. So, for example,
+=head2 C<install_accessors>
 
-  has stuff => (
-    is => 'rw',
-    traits => ['MultiValued::Tags'],
-  );
+After the regular L<Moose::Meta::Attribute> method, installs the
+multi-value accessors.
 
-will create a C<stuff> read / write accessor and a C<stuff_multi> read
-/ write tagged accessor.
+Each installed normal accessor gets a multi-value version
+
+You can add or rename the multi-value version by using the attributes
+described above
+
+If you are passing explicit subrefs for your accessors, things won't work.
+
+=head2 C<load_multi_value>
+
+Retrieves a value from the multi-value object, and stores it in the
+regular slot in the instance. If the value is not found, clears the
+slot.
+
+This traps the
+L<Data::MultiValued::Exceptions::NotFound|Data::MultiValued::Exceptions/Data::MultiValued::Exceptions::NotFound>
+exception that may be thrown by the multi-value object, but re-throws
+any other exception.
+
+=head2 C<raw_clear_value>
+
+Clears the instance slot. Does the same as
+L<Moose::Meta::Attribute/clear_value>, but we need this method because
+the other one gets changed by this trait.
+
+=head2 C<store_multi_value>
+
+Gets the value from the regular slot in the instance, and stores it
+into the multi-value object.
+
+=head2 C<get_value>
+
+Before the normal method, calls L</load_multi_value>. Normally, no
+options will be passed to the multi-value object C<get> method.
+
+=head2 C<get_multi_value>
+
+Sets the options that L</load_multi_value> will use, then calls L</get_value>.
+
+The options are passed via an ugly C<local>ised package
+variable. There might be a better way.
+
+=head2 C<set_initial_value>
+
+After the normal method, calls L</store_multi_value>.
+
+=head2 C<set_value>
+
+=head2 C<set_multi_value>
+
+Just like L</get_value> and L</get_multi_value>, but calling
+L</store_multi_value> after the regular C<set_value>
+
+=head2 C<has_value>
+
+=head2 C<has_multi_value>
+
+Just like L</get_value> and L</get_multi_value>.
+
+=head2 C<clear_value>
+
+=head2 C<clear_multi_value>
+
+Call the C<clear> method on the multi-value object.
+
+=head2 C<get_multi_read_method>
+
+=head2 C<get_multi_write_method>
+
+Return the name of the reader or writer method, honoring
+L</multi_reader>, L</multi_writer> and L</multi_accessor>.
+
+=head2 C<_rebless_slot>
 
-=head1 METHODS
+Blesses the value inside the L</full_storage_slot> of the instance
+into L</multivalue_storage_class>, then calls C<_rebless_storage> on
+it.
+
+=head2 C<_as_hash>
+
+Returns the result of calling C<_as_hash> on the value inside the
+L</full_storage_slot> of the instance. Returns nothing if the slot
+does not have a value.
+
+=head1 DESCRIPTION
 
 =head2 C<slots>
 
@@ -447,18 +519,66 @@ does not have a value.
 
 =head1 ATTRIBUTES
 
-These are the attributes that this trait adds to the attribute in
-your class. Example:
+=head2 C<full_storage_slot>
+
+The instance slot to use to store the C<Data::MultiValued::Tags> or
+similar object. Defaults to C<"${name}__MULTIVALUED_STORAGE__">, where
+C<$name> is the attribute name.
+
+=head2 C<multi_accessor>
+
+=head2 C<multi_reader>
+
+=head2 C<multi_writer>
+
+=head2 C<multi_predicate>
+
+=head2 C<multi_clearer>
+
+The names to use for the various additional accessors. See
+L<Class::MOP::Attribute> for details. These default to
+C<"${name}_multi"> where C<$name> is the name of the corresponding
+non-multi accessor. So, for example,
 
   has stuff => (
     is => 'rw',
-    isa => 'Int',
     traits => ['MultiValued::Tags'],
-    predicate => 'has_stuff',
-    multi_accessor => 'stuff_tagged',
-    multi_predicate => 'has_stuff_tagged',
   );
 
+will create a C<stuff> read / write accessor and a C<stuff_multi> read
+/ write tagged accessor.
+
+=head1 ATTRIBUTES
+
+=head2 C<full_storage_slot>
+
+The instance slot to use to store the C<Data::MultiValued::Tags> or
+similar object. Defaults to C<"${name}__MULTIVALUED_STORAGE__">, where
+C<$name> is the attribute name.
+
+=head2 C<multi_accessor>
+
+=head2 C<multi_reader>
+
+=head2 C<multi_writer>
+
+=head2 C<multi_predicate>
+
+=head2 C<multi_clearer>
+
+The names to use for the various additional accessors. See
+L<Class::MOP::Attribute> for details. These default to
+C<"${name}_multi"> where C<$name> is the name of the corresponding
+non-multi accessor. So, for example,
+
+  has stuff => (
+    is => 'rw',
+    traits => ['MultiValued::Tags'],
+  );
+
+will create a C<stuff> read / write accessor and a C<stuff_multi> read
+/ write tagged accessor.
+
 =head1 Implementation details
 
 The multi-value object is stored in the instance slot named by the