From bd84f294c8d5c8b3680c726b67b6de6391f497cd Mon Sep 17 00:00:00 2001
From: Gianni Ceccarelli <dakkar@thenautilus.net>
Date: Mon, 14 Nov 2011 15:06:52 +0000
Subject: more docs

---
 lib/Data/MultiValued/TagContainer.pm          | 66 +++++++++++++++++++++++++++
 lib/Data/MultiValued/TagContainerForRanges.pm | 32 +++++++++++++
 2 files changed, 98 insertions(+)

diff --git a/lib/Data/MultiValued/TagContainer.pm b/lib/Data/MultiValued/TagContainer.pm
index cdd0456..b7a9b13 100644
--- a/lib/Data/MultiValued/TagContainer.pm
+++ b/lib/Data/MultiValued/TagContainer.pm
@@ -4,6 +4,26 @@ use Moose::Util::TypeConstraints;
 use MooseX::Types::Moose qw(HashRef);
 use Data::MultiValued::Exceptions;
 
+# ABSTRACT: container for tagged values
+
+=head1 DESCRIPTION
+
+Please don't use this module directly, use L<Data::MultiValued::Tags>.
+
+This module implements the storage for tagged data. It's almost
+exactly a hash, the main difference being that C<undef> is a valid key
+and it's distinct from the empty string.
+
+Another difference is that you get an exception if you try to access a
+tag that's not there.
+
+Data is kept in "storage cells", as created by
+L</_create_new_inferior> (by default, a hashref).
+
+=head1 METHODS
+
+=cut
+
 has _storage => (
     is => 'rw',
     isa => HashRef,
@@ -25,6 +45,19 @@ has _default_tag => (
     clearer => '_clear_default_tag',
 );
 
+=head2 C<get>
+
+  my $value = $obj->get({ tag => $the_tag });
+
+Retrieves the "storage cell" for the given tag. Throws a
+L<Data::MultiValued::Exceptions::TagNotFound> exception if the tag
+does not exists in this object.
+
+Not passing in a C<tag> is equivalent to passing in C<< tag => undef
+>>.
+
+=cut
+
 sub get {
     my ($self,$args) = @_;
 
@@ -48,6 +81,19 @@ sub get {
     return $self->_get_tag($tag);
 }
 
+=head2 C<get_or_create>
+
+  $obj->get_or_create({ tag => $the_tag });
+
+Retrieves the "storage cell" for the given tag. If the tag does not
+exist, creates a new cell (see L</_create_new_inferior>), sets it for
+the tag, and returns it.
+
+Not passing in a C<tag> is equivalent to passing in C<< tag => undef
+>>.
+
+=cut
+
 sub get_or_create {
     my ($self,$args) = @_;
 
@@ -76,6 +122,19 @@ sub _clear_storage {
     $self->_storage({});
 }
 
+=head2 C<clear>
+
+  $obj->clear({ tag => $the_tag });
+
+Deletes the given tag and all data associated with it. Does not throw
+exceptions: if the tag does not exist, nothing happens.
+
+Not passing in a C<tag>, or passing C<< tag => undef >>, clears
+everything. If you want to only clear the C<undef> tag, you may call
+C<_clear_default_tag> (which is considered a "protected" method).
+
+=cut
+
 sub clear {
     my ($self,$args) = @_;
 
@@ -91,6 +150,13 @@ sub clear {
     return;
 }
 
+=head2 C<_create_new_inferior>
+
+Returns a new "storage cell", by default an empty hashref. See
+L<Data::MultiValued::TagContainerForRanges> for an example of use.
+
+=cut
+
 sub _create_new_inferior {
     my ($self) = @_;
     return {};
diff --git a/lib/Data/MultiValued/TagContainerForRanges.pm b/lib/Data/MultiValued/TagContainerForRanges.pm
index 604dcb7..9cfc617 100644
--- a/lib/Data/MultiValued/TagContainerForRanges.pm
+++ b/lib/Data/MultiValued/TagContainerForRanges.pm
@@ -4,6 +4,21 @@ use MooseX::Types::Moose qw(HashRef);
 use Moose::Util::TypeConstraints;
 use Data::MultiValued::RangeContainer;
 
+# ABSTRACT: container for tagged values that are ranged containers
+
+=head1 DESCRIPTION
+
+Please don't use this module directly, use
+L<Data::MultiValued::TagsAndRanges>.
+
+This module is a subclass of L<Data::MultiValued::TagContainer>, which
+only allows instances of L<Data::MultiValued::RangeContainer> as
+"storage cells".
+
+=head1 METHODS
+
+=cut
+
 extends 'Data::MultiValued::TagContainer';
 
 has '+_storage' => (
@@ -14,10 +29,27 @@ has '+_default_tag' => (
     isa => class_type('Data::MultiValued::RangeContainer'),
 );
 
+=head2 C<_create_new_inferior>
+
+Returns a new L<Data::MultiValued::RangeContainer> instance.
+
+=cut
+
 sub _create_new_inferior {
     Data::MultiValued::RangeContainer->new();
 }
 
+=head1 Serialisation helpers
+
+These are used through
+L<Data::MultiValued::UglySerializationHelperRole>.
+
+=head2 C<_rebless_storage>
+
+Blesses the "storage cells"
+
+=cut
+
 sub _rebless_storage {
     my ($self) = @_;
     bless $_,'Data::MultiValued::RangeContainer'
-- 
cgit v1.2.3