1 files changed, 93 insertions, 10 deletions
diff --git a/lib/Data/MultiValued/Tags.pm b/lib/Data/MultiValued/Tags.pm
index fbf7948..9c52510 100644
--- a/lib/Data/MultiValued/Tags.pm
+++ b/lib/Data/MultiValued/Tags.pm
@@ -6,7 +6,23 @@ use MooseX::Types::Moose qw(Num Str Undef Any);
 use Data::MultiValued::Exceptions;
 use Data::MultiValued::TagContainer;
 
-# ABSTRACT: Handle values with tags and validity ranges
+# ABSTRACT: Handle values with tags
+
+=head1 SYNOPSIS
+
+  use Data::MultiValued::Tags;
+
+  my $obj = Data::MultiValued::Tags->new();
+  $obj->set({
+    tag => 'tag1',
+    value => 'a string',
+  });
+  say $obj->get({tag=>'tag1'}); # prints 'a string'
+  say $obj->get({tag=>'tag2'}); # dies
+
+=head1 METHODS
+
+=cut
 
 has _storage => (
     is => 'rw',
@@ -19,18 +35,20 @@ sub _build__storage {
     Data::MultiValued::TagContainer->new();
 }
 
-sub _rebless_storage {
-    my ($self) = @_;
+=head2 C<set>
 
-    bless $self->{_storage},'Data::MultiValued::TagContainer';
-}
+  $obj->set({ tag => $the_tag, value => $the_value });
 
-sub _as_hash {
-    my ($self) = @_;
+Stores the given value for the given tag. Replaces existing
+values. Does not throw exceptions.
 
-    my %ret = %{$self->_storage};
-    return {_storage=>\%ret};
-}
+Not passing in a C<tag> is equivalent to passing in C<< tag => undef
+>>.
+
+No cloning is done: if you pass in a reference, the reference is
+just stored.
+
+=cut
 
 sub set {
     my ($self,%args) = validated_hash(
@@ -43,6 +61,22 @@ sub set {
          ->{value} = $args{value};
 }
 
+=head2 C<get>
+
+  my $value = $obj->get({ tag => $the_tag });
+
+Retrieves the value 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
+>>.
+
+No cloning is done: if a reference was stored, you get it back
+untouched.
+
+=cut
+
 sub get {
     my ($self,%args) = validated_hash(
         \@_,
@@ -53,6 +87,18 @@ sub get {
          ->{value};
 }
 
+=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> clears everything. Yes, this means that there
+is no way to just clear the value for the C<undef> tag.
+
+=cut
+
 sub clear {
     my ($self,%args) = validated_hash(
         \@_,
@@ -62,4 +108,41 @@ sub clear {
     $self->_storage->clear(\%args);
 }
 
+=head1 Serialisation helpers
+
+These are used through
+L<Data::MultiValued::UglySerializationHelperRole>.
+
+=head2 C<_rebless_storage>
+
+Blesses the storage into L<Data::MultiValued::TagContainer>.
+
+=cut
+
+sub _rebless_storage {
+    my ($self) = @_;
+
+    bless $self->{_storage},'Data::MultiValued::TagContainer';
+}
+
+=head2 C<_as_hash>
+
+Returns the internal representation with no blessed hashes, with as
+few copies as possible.
+
+=cut
+
+sub _as_hash {
+    my ($self) = @_;
+
+    my %ret = %{$self->_storage};
+    return {_storage=>\%ret};
+}
+
+=head1 SEE ALSO
+
+L<Data::MultiValued::TagContainer>, L<Data::MultiValued::Exceptions>
+
+=cut
+
 1;