From: Dave Rolsky <autarch@houseabsolute.urth.org>
Date: Wed, 25 Mar 2009 22:37:45 +0000 (-0500)
Subject: Docs for MM::TC::Union
X-Git-Tag: 0.72_01~15
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=ae2f99ea2b5f853ca3fa7204f5fefb0ce6ce22cd;p=gitmo%2FMoose.git

Docs for MM::TC::Union
---

diff --git a/lib/Moose/Meta/TypeConstraint/Union.pm b/lib/Moose/Meta/TypeConstraint/Union.pm
index c4508b2..4a3a542 100644
--- a/lib/Moose/Meta/TypeConstraint/Union.pm
+++ b/lib/Moose/Meta/TypeConstraint/Union.pm
@@ -144,77 +144,73 @@ Moose::Meta::TypeConstraint::Union - A union of Moose type constraints
 
 =head1 DESCRIPTION
 
-This metaclass represents a union of Moose type constraints. More 
-details to be explained later (possibly in a Cookbook recipe).
+This metaclass represents a union of type constraints. A union takes
+multiple type constraints, and is true if any one of its member
+constraints is true.
 
-This actually used to be part of Moose::Meta::TypeConstraint, but it 
-is now better off in it's own file. 
+=head1 INHERITANCE
 
-=head1 METHODS
-
-This class is not a subclass of Moose::Meta::TypeConstraint, 
-but it does provide the same API
+C<Moose::Meta::TypeConstraint::Union> is a subclass of
+L<Moose::Meta::TypeConstraint>.
 
 =over 4
 
-=item B<meta>
-
-=item B<new>
-
-=item B<name>
-
-=item B<type_constraints>
-
-=item B<parents>
-
-=item B<constraint>
+=item B<< Moose::Meta::TypeConstraint::Union->new(%options) >>
 
-=item B<includes_type>
+This creates a new class type constraint based on the given
+C<%options>.
 
-=item B<equals>
+It takes the same options as its parent. It also requires an
+additional option, C<type_constraints>. This is an array reference
+containing the L<Moose::Meta::TypeConstraint> objects that are the
+members of the union type. The C<name> option defaults to the names
+all of these member types sorted and then joined by a pipe (|).
 
-=back
-
-=head2 Overridden methods 
-
-=over 4
+The constructor sets the implementation of the constraint so that is
+simply calls C<check> on the newly created object.
 
-=item B<check>
+Finally, the constructor also makes sure that the object's C<coercion>
+attribute is a L<Moose::Meta::TypeCoercion::Union> object.
 
-=item B<coerce>
+=item B<< $constraint->type_constraints >>
 
-=item B<validate>
+This returns the array reference of C<type_constraints> provided to
+the constructor.
 
-=item B<is_a_type_of>
+=item B<< $constraint->parents >>
 
-=item B<is_subtype_of>
+This returns the same constraint as the C<type_constraints> method.
 
-=back
+=item B<< $constraint->check($value) >>
 
-=head2 Empty or Stub methods
+=item B<< $constraint->validate($value) >>
 
-These methods tend to not be very relevant in 
-the context of a union. Either that or they are 
-just difficult to specify and not very useful 
-anyway. They are here for completeness.
+These two methods simply call the relevant method on each of the
+member type constraints in the union. If any type accepts the value,
+the value is valid.
 
-=over 4
+With C<validate> the error message returned includes all of the error
+messages returned by the member type constraints.
 
-=item B<parent>
+=item B<< $constraint->equals($type_name_or_object) >>
 
-=item B<coercion>
+A type is considered equal if it is also a union type, and the two
+unions have the same member types.
 
-=item B<has_coercion>
+=item B<< $constraint->is_a_type_of($type_name_or_object) >>
 
-=item B<message>
+This returns true if any of the member type constraints return true
+for the C<is_a_type_of> method.
 
-=item B<has_message>
+=item B<< $constraint->is_subtype_of >>
 
-=item B<hand_optimized_type_constraint>
+This returns true if any of the member type constraints return true
+for the C<is_a_subtype_of> method.
 
-=item B<has_hand_optimized_type_constraint>
+=item B<< $constraint->create_child_type(%options) >>
 
-=item B<create_child_type>
+This returns a new L<Moose::Meta::TypeConstraint> object with the type
+as its parent.
 
 =back