Improve documentation on Moose::Util::TypConstraints "role_type" and "class_type"

The documentation for mapping custom type-library names to class names
is a bit lacking, to the point people actually do this:

subtype 'Foo', as 'Ref', where { $_->meta->does('Class::Foo') }

instead of the simple alternative

  role_type 'Foo', { role => 'Class::Foo' }

I bump into this problem reasonably often, and each time I bump into it
I forget exactly what the right syntax is, and usually end up writing
something like

  role_type 'Foo', { does => 'Class::Foo' }

Which silently fails to do what I meant, and then doesn't work as
intended.

I then often spend time perusing much documentation and wasting much
time tracking down where exactly its documented, and finding "it isn't",
and then proceed to reading the source to find what I'm doing
wrong.

( Oddly, I manage to get better at finding the right place in the
  source to look because somehow I can remember where I looked when I
  saw it last, but I can't remember exactly what the right syntax was ).

So, this simple patch aims to improve that and hopefully at least save
many minutes of my time, and perhaps the time of dozens more people.

( its not documented in MX::Types either, if anything, if you want to
  use MX::Types, the easiest thing to do is read MUTC's documentation
  instead )

diff --git a/lib/Moose/Util/TypeConstraints.pm b/lib/Moose/Util/TypeConstraints.pm
index 43c5911..92652b9 100644 (file)
--- a/lib/Moose/Util/TypeConstraints.pm
+++ b/lib/Moose/Util/TypeConstraints.pm
@@ -750,6 +750,10 @@ __END__
       from 'Str',
       via { 0+$_ };
 
+  class_type 'DateTimeish', { class => 'DateTime' };
+
+  role_type 'Barks', { role => 'Some::Library::Role::Barks' };
+
   enum 'RGBColors', [qw(red green blue)];
 
   union 'StringOrArray', [qw( String Array )];
@@ -959,11 +963,31 @@ just a hashref of parameters:
 Creates a new subtype of C<Object> with the name C<$class> and the
 metaclass L<Moose::Meta::TypeConstraint::Class>.
 
+  # Create a type called 'Box' which tests for objects which ->isa('Box')
+  class_type 'Box';
+
+Additionally, you can create a class_type which is a shorthand for another class.
+
+  # Create a type called 'Box' which tests for objects which ->isa('ObjectLibrary::Box');
+  class_type 'Box', { class => 'ObjectLibrary::Box' };
+
+But it's only really necessary to do this if you're working with L<MooseX::Types>.
+
 =item B<role_type ($role, ?$options)>
 
 Creates a C<Role> type constraint with the name C<$role> and the
 metaclass L<Moose::Meta::TypeConstraint::Role>.
 
+  # Create a type called 'Walks' which tests for objects which ->does('Walks')
+  role_type 'Walks';
+
+Additionally, you can create a role_type which is a shorthand for another role.
+
+  # Create a type called 'Walks' which tests for objects which ->does('MooseX::Role::Walks');
+  role_type 'Walks', { role => 'MooseX::Role::Walks' };
+
+But it's only really necessary to do this if you're working with L<MooseX::Types>.
+
 =item B<maybe_type ($type)>
 
 Creates a type constraint for either C<undef> or something of the