1 files changed, 91 insertions, 11 deletions

diff --git a/lib/Data/MultiValued/TagsAndRanges.pm b/lib/Data/MultiValued/TagsAndRanges.pm
index 6208435..204f858 100644
--- a/lib/Data/MultiValued/TagsAndRanges.pm
+++ b/lib/Data/MultiValued/TagsAndRanges.pm
@@ -8,6 +8,25 @@ use Data::MultiValued::TagContainerForRanges;
 
 # ABSTRACT: Handle values with tags and validity ranges
 
+=head1 SYNOPSIS
+
+  use Data::MultiValued::TagsAndRanges;
+
+  my $obj = Data::MultiValued::TagsAndRanges->new();
+  $obj->set({
+    tag => 'tag1',
+    from => 10,
+    to => 20,
+    value => 'foo',
+  });
+  say $obj->get({tag => 'tag1', at => 15}); # prints 'foo'
+  say $obj->get({tag => 'tag1', at => 35}); # dies
+  say $obj->get({tag => 'tag2', at => 15}); # dies
+
+=head1 METHODS
+
+=cut
+
 has _storage => (
     is => 'rw',
     isa => class_type('Data::MultiValued::TagContainerForRanges'),
@@ -19,19 +38,17 @@ sub _build__storage {
     Data::MultiValued::TagContainerForRanges->new();
 }
 
-sub _rebless_storage {
-    my ($self) = @_;
+=head2 C<set>
 
-    bless $self->{_storage},'Data::MultiValued::TagContainerForRanges';
-    $self->_storage->_rebless_storage;
-}
+  $obj->set({ tag => $the_tag, from => $min, to => $max, value => $the_value });
 
-sub _as_hash {
-    my ($self) = @_;
+Stores the given value for the given tag and range. Does not throw
+exceptions.
 
-    my $ret = $self->_storage->_as_hash;
-    return {_storage=>$ret};
-}
+See L<Data::MultiValued::Tags/set> and
+L<Data::MultiValued::Ranges/set> for more details.
+
+=cut
 
 sub set {
     my ($self,%args) = validated_hash(
@@ -43,10 +60,25 @@ sub set {
     );
 
     $self->_storage->get_or_create(\%args)
-         ->set_or_create(\%args)
+         ->get_or_create(\%args)
          ->{value} = $args{value};
 }
 
+=head2 C<get>
+
+  my $value = $obj->get({ tag => $the_tag, at => $point });
+
+Retrieves the value for the given tag and point. Throws a
+L<Data::MultiValued::Exceptions::RangeNotFound> exception if no ranges
+exist in this object that include the point, and
+L<Data::MultiValued::Exceptions::TagNotFound> exception if the tag
+does not exists in this object.
+
+See L<Data::MultiValued::Tags/get> and
+L<Data::MultiValued::Ranges/get> for more details.
+
+=cut
+
 sub get {
     my ($self,%args) = validated_hash(
         \@_,
@@ -59,6 +91,20 @@ sub get {
          ->{value};
 }
 
+=head2 C<clear>
+
+  $obj->clear({ tag => $the_tag, from => $min, to => $max });
+
+If a range is specified, deletes all values for the given range and
+tag. If no range is specified, delete all values for the given tag.
+
+Does not throw exceptions.
+
+See L<Data::MultiValued::Tags/clear> and
+L<Data::MultiValued::Ranges/clear> for more details.
+
+=cut
+
 sub clear {
     my ($self,%args) = validated_hash(
         \@_,
@@ -76,4 +122,38 @@ sub clear {
     }
 }
 
+=head1 Serialisation helpers
+
+These are used through
+L<Data::MultiValued::UglySerializationHelperRole>.
+
+=head2 C<_rebless_storage>
+
+Blesses the storage into L<Data::MultiValued::TagContainerForRanges>,
+then calls C<_rebless_storage> on it.
+
+=cut
+
+sub _rebless_storage {
+    my ($self) = @_;
+
+    bless $self->{_storage},'Data::MultiValued::TagContainerForRanges';
+    $self->_storage->_rebless_storage;
+}
+
+=head2 C<_as_hash>
+
+Returns the internal representation with no blessed hashes, with as
+few copies as possible. Depends on
+L<Data::MultiValued::TagContainerForRanges/_as_hash>.
+
+=cut
+
+sub _as_hash {
+    my ($self) = @_;
+
+    my $ret = $self->_storage->_as_hash;
+    return {_storage=>$ret};
+}
+
 1;