Improve documentation on Moose::Util::TypConstraints "role_type" and "class_type"
authorKent Fredric <kentfredric@gmail.com>
Tue, 16 Aug 2011 16:03:09 +0000 (04:03 +1200)
committerDave Rolsky <autarch@urth.org>
Mon, 29 Aug 2011 16:05:43 +0000 (11:05 -0500)
commit83aa5247744b4d1d8b9985cdaee06aefb3a82c3c
treece98b8fb10650655871966266951f4b115bc8902
parenteb2c02c4be7231c9b531691b2f4f35ab6134c580
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 )
lib/Moose/Util/TypeConstraints.pm