From: Fuji, Goro Date: Wed, 10 Nov 2010 07:14:57 +0000 (+0900) Subject: Make docs more alike to Moose X-Git-Tag: 0.85~2 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=0f9137462d2e2fd1fa285417383adbf64614a91d;p=gitmo%2FMouse.git Make docs more alike to Moose --- diff --git a/lib/Mouse.pm b/lib/Mouse.pm index a1687f6..3508380 100644 --- a/lib/Mouse.pm +++ b/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 for the latter, if possible. +Moose (we recommend that you instead use persistent Perl executing environments +like C 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 except for testing modules. Mouse also works without XS, -although it has an XS backend to make it much faster. +B 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 on your codebase and have nothing break. To that end, @@ -225,7 +225,7 @@ also better. See also L 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! diff --git a/lib/Mouse/Role.pm b/lib/Mouse/Role.pm index dfa08d9..b38dfed 100644 --- a/lib/Mouse/Role.pm +++ b/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. +This document serves as API documentation. -=head2 C<< before (method|methods|regexp) -> CodeRef >> +=head1 EXPORTED FUNCTIONS -Sets up a B method modifier. See L. +Mouse::Role supports all of the functions that Mouse exports, but +differs slightly in how some items are handled (see L below +for details). -=head2 C<< after (method|methods|regexp) => CodeRef >> +Mouse::Role also offers two role-specific keywords: -Sets up an B method modifier. See L. +=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 the role. -Sets up an B method modifier. See L. +Note that attribute accessors also count as methods for the purposes of +satisfying the requirements of a role. -=head2 C +=head2 C<< excludes(@role_names) >> -Sets up the B keyword. See L. +This is exported but not implemented in Mouse. -=head2 C<< override method => CodeRef >> +=head1 IMPORT AND UNIMPORT -Sets up an B method modifier. See L. - -=head2 C - -This is not supported in roles and emits an error. See L. - -=head2 C<< augment method => CodeRef >> +=head2 import -This is not supported in roles and emits an error. See L. +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. +Please unimport (C<< no Mouse::Role >>) so that if someone calls one of the +keywords (such as L) it will break loudly instead breaking subtly. -=head2 C<< confess(error) -> BOOM >> +=head1 CAVEATS -L for your convenience. +Role support has only a few caveats: -=head2 C<< blessed(value) -> ClassName | undef >> +=over -L for your convenience. +=item * -=head1 MISC +Roles cannot use the C keyword; it will throw an exception for now. +The same is true of the C and C keywords (not sure those +really make sense for roles). All other Mouse keywords will be I +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 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) it will break loudly instead breaking subtly. +=back =head1 SEE ALSO +L + L =cut diff --git a/xt/002-pod_spell.t b/xt/002-pod_spell.t index 0266894..dc94220 100644 --- a/xt/002-pod_spell.t +++ b/xt/002-pod_spell.t @@ -278,6 +278,8 @@ reimplements reinitializes specializer backend +extention +extentions ## misspelt on purpose emali