Make docs more alike to Moose

lib/Mouse.pm

@@ -196,21 +196,21 @@ Unfortunately, Moose has a compile-time penalty. Though significant progress
 has been made over the years, the compile time penalty is a non-starter for
 some very specific applications. If you are writing a command-line application
 or CGI script where startup time is essential, you may not be able to use
-Moose. We recommend that you instead use persistent Perl executing environments
-like C<FastCGI> for the latter, if possible.
+Moose (we recommend that you instead use persistent Perl executing environments
+like C<FastCGI> for the latter, if possible).
 
-Mouse is a Moose compatible object system, which aims to alleviate this by
-providing a subset of Moose's functionality.
+Mouse is a Moose compatible object system, which aims to alleviate this penalty
+by providing a subset of Moose's functionality.
 
 We're also going as light on dependencies as possible. Mouse currently has
-B<no dependencies> except for testing modules. Mouse also works without XS,
-although it has an XS backend to make it much faster.
+B<no dependencies> except for building/testing modules. Mouse also works
+without XS, although it has an XS backend to make it much faster.
 
-=head2 MOOSE COMPATIBILITY
+=head2 Moose Compatibility
 
 Compatibility with Moose has been the utmost concern. The sugary interface is
 highly compatible with Moose. Even the error messages are taken from Moose.
-The Mouse code just runs the test suite 4x faster.
+The Mouse code just runs its test suite 4x faster.
 
 The idea is that, if you need the extra power, you should be able to run
 C<s/Mouse/Moose/g> on your codebase and have nothing break. To that end,
@@ -225,7 +225,7 @@ also better.
 
 See also L<Mouse::Spec> for compatibility and incompatibility with Moose.
 
-=head2 MouseX
+=head2 Mouse Extentions
 
 Please don't copy MooseX code to MouseX. If you need extensions, you really
 should upgrade to Moose. We don't need two parallel sets of extensions!

lib/Mouse/Role.pm

@@ -166,66 +166,76 @@ This document describes Mouse version 0.84
     my $bar = MyObject->new();
     $obj->equals($bar); # yes, it is comparable
 
-=head1 KEYWORDS
+=head1 DESCRIPTION
 
-=head2 C<< meta -> Mouse::Meta::Role >>
+This module declares the caller class to be a Mouse role.
 
-Returns this role's metaclass instance.
+The concept of roles is documented in L<Moose::Manual::Roles>.
+This document serves as API documentation.
 
-=head2 C<< before (method|methods|regexp) -> CodeRef >>
+=head1 EXPORTED FUNCTIONS
 
-Sets up a B<before> method modifier. See L<Moose/before>.
+Mouse::Role supports all of the functions that Mouse exports, but
+differs slightly in how some items are handled (see L</CAVEATS> below
+for details).
 
-=head2 C<< after (method|methods|regexp) => CodeRef >>
+Mouse::Role also offers two role-specific keywords:
 
-Sets up an B<after> method modifier. See L<Moose/after>.
+=head2 C<< requires(@method_names) >>
 
-=head2 C<< around (method|methods|regexp) => CodeRef >>
+Roles can require that certain methods are implemented by any class which
+C<does> the role.
 
-Sets up an B<around> method modifier. See L<Moose/around>.
+Note that attribute accessors also count as methods for the purposes of
+satisfying the requirements of a role.
 
-=head2 C<super>
+=head2 C<< excludes(@role_names) >>
 
-Sets up the B<super> keyword. See L<Moose/super>.
+This is exported but not implemented in Mouse.
 
-=head2  C<< override method => CodeRef >>
+=head1 IMPORT AND UNIMPORT
 
-Sets up an B<override> method modifier. See L<Moose/Role/override>.
-
-=head2 C<inner>
-
-This is not supported in roles and emits an error. See L<Moose/Role>.
-
-=head2 C<< augment method => CodeRef >>
+=head2 import
 
-This is not supported in roles and emits an error. See L<Moose/Role>.
+Importing Mouse::Role will give you sugar. C<-traits> are also supported.
 
-=head2 C<< has (name|names) => parameters >>
+=head2 unimport
 
-Sets up an attribute (or if passed an arrayref of names, multiple attributes) to
-this role. See L<Mouse/has>.
+Please unimport (C<< no Mouse::Role >>) so that if someone calls one of the
+keywords (such as L</has>) it will break loudly instead breaking subtly.
 
-=head2 C<< confess(error) -> BOOM >>
+=head1 CAVEATS
 
-L<Carp/confess> for your convenience.
+Role support has only a few caveats:
 
-=head2 C<< blessed(value) -> ClassName | undef >>
+=over
 
-L<Scalar::Util/blessed> for your convenience.
+=item *
 
-=head1 MISC
+Roles cannot use the C<extends> keyword; it will throw an exception for now.
+The same is true of the C<augment> and C<inner> keywords (not sure those
+really make sense for roles). All other Mouse keywords will be I<deferred>
+so that they can be applied to the consuming class.
 
-=head2 import
+=item *
 
-Importing Mouse::Role will give you sugar.
+Role composition does its best to B<not> be order-sensitive when it comes to
+conflict resolution and requirements detection. However, it is order-sensitive
+when it comes to method modifiers. All before/around/after modifiers are
+included whenever a role is composed into a class, and then applied in the order
+in which the roles are used. This also means that there is no conflict for
+before/around/after modifiers.
 
-=head2 unimport
+In most cases, this will be a non-issue; however, it is something to keep in
+mind when using method modifiers in a role. You should never assume any
+ordering.
 
-Please unimport (C<< no Mouse::Role >>) so that if someone calls one of the
-keywords (such as L</has>) it will break loudly instead breaking subtly.
+=back
 
 =head1 SEE ALSO
 
+L<Mouse>
+
 L<Moose::Role>
 
 =cut

xt/002-pod_spell.t

@@ -278,6 +278,8 @@ reimplements
 reinitializes
 specializer
 backend
+extention
+extentions
 
 ## misspelt on purpose
 emali