From: Tomas Doran (t0m) <t0m@state51.co.uk>
Date: Mon, 13 Jul 2009 21:37:10 +0000 (+0100)
Subject: Add docs for the undocumented classes
X-Git-Tag: 0.20~4
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=511f9c4baa29713783b2cebdb69a441ffe2190a3;p=gitmo%2FMooseX-Storage.git

Add docs for the undocumented classes
---

diff --git a/lib/MooseX/Storage/Engine/Trait/DisableCycleDetection.pm b/lib/MooseX/Storage/Engine/Trait/DisableCycleDetection.pm
index b0ab38c..db732de 100644
--- a/lib/MooseX/Storage/Engine/Trait/DisableCycleDetection.pm
+++ b/lib/MooseX/Storage/Engine/Trait/DisableCycleDetection.pm
@@ -9,3 +9,64 @@ around 'check_for_cycle_in_collapse' => sub {
 
 1;
 
+=head1 NAME
+
+MooseX::Storage::Engine::Trait::DisableCycleDetection - A custom trait to bypass cycle detection
+
+=head1 SYNOPSIS
+
+    package Double;
+    use Moose;
+    use MooseX::Storage;
+    with Storage( traits => ['DisableCycleDetection'] );
+
+    has 'x' => ( is => 'rw', isa => 'HashRef' );
+    has 'y' => ( is => 'rw', isa => 'HashRef' );
+
+    my $ref = {};
+
+    my $double = Double->new( 'x' => $ref, 'y' => $ref );
+
+    $double->pack;
+
+=head1 DESCRIPTION
+
+C<MooseX::Storage> implements a primitive check for circular references.
+This check also triggers on simple cases as shown in the Synopsis.
+Providing the C<DisableCycleDetection> traits disables checks for any cyclical
+references, so if you know what you are doing, you can bypass this check.
+
+This trait is applied to an instance of L<MooseX::Storage::Engine>, for the
+user-visible version shown in the SYNOPSIS, see L<MooseX::Storage::Traits::DisableCycleDetection>
+
+=head1 METHODS
+
+=head2 Introspection
+
+=over 4
+
+=item B<meta>
+
+=back
+
+=head1 BUGS
+
+All complex software has bugs lurking in it, and this module is no
+exception. If you find a bug please either email me, or add the bug
+to cpan-RT.
+
+=head1 AUTHOR
+
+Stevan Little E<lt>stevan.little@iinteractive.comE<gt>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2007-2008 by Infinity Interactive, Inc.
+
+L<http://www.iinteractive.com>
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
+
+=cut
+
diff --git a/lib/MooseX/Storage/Engine/Trait/OnlyWhenBuilt.pm b/lib/MooseX/Storage/Engine/Trait/OnlyWhenBuilt.pm
index 461c980..427dfb4 100644
--- a/lib/MooseX/Storage/Engine/Trait/OnlyWhenBuilt.pm
+++ b/lib/MooseX/Storage/Engine/Trait/OnlyWhenBuilt.pm
@@ -3,7 +3,7 @@ use Moose::Role;
 
 # we should
 # only serialize the attribute if it's already built. So, go ahead
-# and check if the attribute has a predicate. If so, check if it's 
+# and check if the attribute has a predicate. If so, check if it's
 # set  and then go ahead and look it up.
 around 'collapse_attribute' => sub {
     my ($orig, $self, $attr, @args) = @_;
@@ -18,3 +18,76 @@ around 'collapse_attribute' => sub {
 
 1;
 
+__END__
+
+=pod
+
+=head1 NAME
+
+MooseX::Storage::Engine::Trait::OnlyWhenBuilt - An engine trait to bypass serialization
+
+=head1 SYNOPSIS
+
+    {   package Point;
+        use Moose;
+        use MooseX::Storage;
+
+        with Storage( traits => [qw|OnlyWhenBuilt|] );
+
+        has 'x' => (is => 'rw', lazy_build => 1 );
+        has 'y' => (is => 'rw', lazy_build => 1 );
+        has 'z' => (is => 'rw', builder => '_build_z' );
+
+        sub _build_x { 3 }
+        sub _build_y { expensive_computation() }
+        sub _build_z { 3 }
+    }
+
+    my $p = Point->new( 'x' => 4 );
+
+    # the result of ->pack will contain:
+    # { x => 4, z => 3 }
+    $p->pack;
+
+=head1 DESCRIPTION
+
+Sometimes you don't want a particular attribute to be part of the
+serialization if it has not been built yet. If you invoke C<Storage()>
+as outlined in the C<Synopsis>, only attributes that have been built
+(ie, where the predicate returns 'true') will be serialized.
+This avoids any potentially expensive computations.
+
+This trait is applied to an instance of L<MooseX::Storage::Engine>, for the
+user-visible version shown in the SYNOPSIS, see L<MooseX::Storage::Traits::OnlyWhenBuilt>
+
+=head1 METHODS
+
+=head2 Introspection
+
+=over 4
+
+=item B<meta>
+
+=back
+
+=head1 BUGS
+
+All complex software has bugs lurking in it, and this module is no
+exception. If you find a bug please either email me, or add the bug
+to cpan-RT.
+
+=head1 AUTHOR
+
+Stevan Little E<lt>stevan.little@iinteractive.comE<gt>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2007-2008 by Infinity Interactive, Inc.
+
+L<http://www.iinteractive.com>
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
+
+=cut
+