From: gfx Date: Fri, 25 Sep 2009 07:02:04 +0000 (+0900) Subject: Improve documents X-Git-Tag: 0.35~25 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=1820fffecb0bd1da64edc16ecde534178b841d14;p=gitmo%2FMouse.git Improve documents --- diff --git a/lib/Mouse.pm b/lib/Mouse.pm index 9b01f93..c07b200 100644 --- a/lib/Mouse.pm +++ b/lib/Mouse.pm @@ -247,7 +247,7 @@ We're also going as light on dependencies as possible. L or L is required if you want support for L, L, and L. -=head2 MOOSE COMPAT +=head2 MOOSE COMPATIBILITY Compatibility with Moose has been the utmost concern. Fewer than 1% of the tests fail when run against Moose instead of Mouse. Mouse code coverage is also @@ -281,52 +281,52 @@ If you would like to help maintain this module, please get in touch with us. =head1 KEYWORDS -=head2 meta -> Mouse::Meta::Class +=head2 C<< $object->meta -> Mouse::Meta::Class >> Returns this class' metaclass instance. -=head2 extends superclasses +=head2 C<< extends superclasses >> Sets this class' superclasses. -=head2 before (method|methods) => Code +=head2 C<< before (method|methods) => CodeRef >> Installs a "before" method modifier. See L or L. Use of this feature requires L! -=head2 after (method|methods) => Code +=head2 C<< after (method|methods) => CodeRef >> Installs an "after" method modifier. See L or L. Use of this feature requires L! -=head2 around (method|methods) => Code +=head2 C<< around (method|methods) => CodeRef >> Installs an "around" method modifier. See L or L. Use of this feature requires L! -=head2 has (name|names) => parameters +=head2 C<< has (name|names) => parameters >> Adds an attribute (or if passed an arrayref of names, multiple attributes) to this class. Options: =over 4 -=item is => ro|rw +=item C<< is => ro|rw|bare >> If specified, inlines a read-only/read-write accessor with the same name as the attribute. -=item isa => TypeConstraint +=item C<< isa => TypeConstraint >> Provides type checking in the constructor and accessor. The following types are -supported. Any unknown type is taken to be a class check (e.g. isa => -'DateTime' would accept only L objects). +supported. Any unknown type is taken to be a class check +(e.g. C<< isa => 'DateTime' >> would accept only L objects). Any Item Bool Undef Defined Value Num Int Str ClassName Ref ScalarRef ArrayRef HashRef CodeRef RegexpRef GlobRef @@ -335,85 +335,90 @@ supported. Any unknown type is taken to be a class check (e.g. isa => For more documentation on type constraints, see L. -=item required => 0|1 +=item C<< required => Bool >> Whether this attribute is required to have a value. If the attribute is lazy or has a builder, then providing a value for the attribute in the constructor is optional. -=item init_arg => Str | Undef +=item C<< init_arg => Str | Undef >> Allows you to use a different key name in the constructor. If undef, the -attribue can't be passed to the constructor. +attribute can't be passed to the constructor. -=item default => Value | CodeRef +=item C<< default => Value | CodeRef >> Sets the default value of the attribute. If the default is a coderef, it will be invoked to get the default value. Due to quirks of Perl, any bare reference is forbidden, you must wrap the reference in a coderef. Otherwise, all instances will share the same reference. -=item lazy => 0|1 +=item C<< lazy => Bool >> If specified, the default is calculated on demand instead of in the constructor. -=item predicate => Str +=item C<< predicate => Str >> Lets you specify a method name for installing a predicate method, which checks that the attribute has a value. It will not invoke a lazy default or builder method. -=item clearer => Str +=item C<< clearer => Str >> Lets you specify a method name for installing a clearer method, which clears the attribute's value from the instance. On the next read, lazy or builder will be invoked. -=item handles => HashRef|ArrayRef +=item C<< handles => HashRef|ArrayRef >> Lets you specify methods to delegate to the attribute. ArrayRef forwards the given method names to method calls on the attribute. HashRef maps local method names to remote method names called on the attribute. Other forms of L, such as regular expression and coderef, are not yet supported. -=item weak_ref => 0|1 +=item C<< weak_ref => Bool >> Lets you automatically weaken any reference stored in the attribute. Use of this feature requires L! -=item trigger => CodeRef +=item C<< trigger => CodeRef >> Any time the attribute's value is set (either through the accessor or the constructor), the trigger is called on it. The trigger receives as arguments the instance, the new value, and the attribute instance. -Mouse 0.05 supported more complex triggers, but this behavior is now removed. - -=item builder => Str +=item C<< builder => Str >> Defines a method name to be called to provide the default value of the attribute. C<< builder => 'build_foo' >> is mostly equivalent to C<< default => sub { $_[0]->build_foo } >>. -=item auto_deref => 0|1 +=item C<< auto_deref => Bool >> Allows you to automatically dereference ArrayRef and HashRef attributes in list context. In scalar context, the reference is returned (NOT the list length or bucket status). You must specify an appropriate type constraint to use auto_deref. -=item lazy_build => 0|1 +=item C<< lazy_build => Bool >> + +Automatically define the following options: -Automatically define lazy => 1 as well as builder => "_build_$attr", clearer => -"clear_$attr', predicate => 'has_$attr' unless they are already defined. + has $attr => ( + # ... + lazy => 1 + builder => "_build_$attr", + clearer => "clear_$attr", + predicate => "has_$attr", + ); =back -=head2 confess error -> BOOM +=head2 C<< confess(message) -> BOOM >> L for your convenience. -=head2 blessed value -> ClassName | undef +=head2 C<< blessed(value) -> ClassName | undef >> L for your convenience. @@ -429,25 +434,21 @@ You may use L to replace the superclass list. Please unimport Mouse (C) so that if someone calls one of the keywords (such as L) it will break loudly instead breaking subtly. -=head1 FUNCTIONS +=head1 SOURCE CODE ACCESS -=head2 load_class Class::Name +We have a public git repository: -This will load a given C (or die if it's not loadable). -This function can be used in place of tricks like -C or using C. + git clone git://jules.scsys.co.uk/gitmo/Mouse.git -=head2 is_class_loaded Class::Name -> Bool +=head1 DEPENDENCIES -Returns whether this class is actually loaded or not. It uses a heuristic which -involves checking for the existence of C<$VERSION>, C<@ISA>, and any -locally-defined method. +Perl 5.6.2 or later. -=head1 SOURCE CODE ACCESS +=head1 SEE ALSO -We have a public git repo: +L - git clone git://jules.scsys.co.uk/gitmo/Mouse.git +L =head1 AUTHORS @@ -467,13 +468,9 @@ with plenty of code borrowed from L and L =head1 BUGS -There is a known issue with Mouse on 5.6.2 regarding the @ISA tests. Until -this is resolve the minimum version of Perl for Mouse is set to 5.8.0. Patches -to resolve these tests are more than welcome. - -Please report any bugs through RT: email -C, or browse -L. +All complex software has bugs lurking in it, and this module is no exception. +Please report any bugs to C, or through the web +interface at L =head1 COPYRIGHT AND LICENSE diff --git a/lib/Mouse/Meta/Attribute.pm b/lib/Mouse/Meta/Attribute.pm index ec752cb..1845219 100644 --- a/lib/Mouse/Meta/Attribute.pm +++ b/lib/Mouse/Meta/Attribute.pm @@ -368,85 +368,123 @@ Mouse::Meta::Attribute - attribute metaclass =head1 METHODS -=head2 new %args -> Mouse::Meta::Attribute +=head2 C<< new(%options) -> Mouse::Meta::Attribute >> Instantiates a new Mouse::Meta::Attribute. Does nothing else. -=head2 create OwnerClass, AttributeName, %args -> Mouse::Meta::Attribute +It adds the following options to the constructor: -Creates a new attribute in OwnerClass. Accessors and helper methods are -installed. Some error checking is done. +=over 4 -=head2 name -> AttributeName +=item * C<< is => 'ro', 'rw', 'bare' >> -=head2 associated_class -> OwnerClass +This provides a shorthand for specifying the C, C, or +C names. If the attribute is read-only ('ro') then it will +have a C method with the same attribute as the name. -=head2 is_required -> Bool +If it is read-write ('rw') then it will have an C method +with the same name. If you provide an explicit C for a +read-write attribute, then you will have a C with the same +name as the attribute, and a C with the name you provided. -=head2 default -> Item +Use 'bare' when you are deliberately not installing any methods +(accessor, reader, etc.) associated with this attribute; otherwise, +Moose will issue a deprecation warning when this attribute is added to a +metaclass. -=head2 has_default -> Bool +=item * C<< isa => Type >> -=head2 is_lazy -> Bool +This option accepts a type. The type can be a string, which should be +a type name. If the type name is unknown, it is assumed to be a class +name. -=head2 predicate -> MethodName | Undef +This option can also accept a L object. -=head2 has_predicate -> Bool +If you I provide a C option, then your C option must +be a class name, and that class must do the role specified with +C. -=head2 clearer -> MethodName | Undef +=item * C<< does => Role >> -=head2 has_clearer -> Bool +This is short-hand for saying that the attribute's type must be an +object which does the named role. -=head2 handles -> { LocalName => RemoteName } +B -=head2 has_handles -> Bool +=item * C<< coerce => Bool >> -=head2 is_weak_ref -> Bool +This option is only valid for objects with a type constraint +(C). If this is true, then coercions will be applied whenever +this attribute is set. -=head2 init_arg -> Str +You can make both this and the C option true. -=head2 type_constraint -> Str +=item * C<< trigger => CodeRef >> -=head2 has_type_constraint -> Bool +This option accepts a subroutine reference, which will be called after +the attribute is set. -=head2 trigger => CODE | Undef +=item * C<< required => Bool >> -=head2 has_trigger -> Bool +An attribute which is required must be provided to the constructor. An +attribute which is required can also have a C or C, +which will satisfy its required-ness. -=head2 builder => MethodName | Undef +A required attribute must have a C, C or a +non-C C -=head2 has_builder -> Bool +=item * C<< lazy => Bool >> -=head2 is_lazy_build => Bool +A lazy attribute must have a C or C. When an +attribute is lazy, the default value will not be calculated until the +attribute is read. -=head2 should_auto_deref -> Bool +=item * C<< weak_ref => Bool >> -Informational methods. +If this is true, the attribute's value will be stored as a weak +reference. -=head2 verify_against_type_constraint Item -> 1 | ERROR +=item * C<< auto_deref => Bool >> -Checks that the given value passes this attribute's type constraint. Returns 1 -on success, otherwise Ces. +If this is true, then the reader will dereference the value when it is +called. The attribute must have a type constraint which defines the +attribute as an array or hash reference. + +=item * C<< lazy_build => Bool >> + +Setting this to true makes the attribute lazy and provides a number of +default methods. -=head2 canonicalize_args Name, %args -> %args + has 'size' => ( + is => 'ro', + lazy_build => 1, + ); -Canonicalizes some arguments to create. In particular, C is -canonicalized into C, C, etc. +is equivalent to this: -=head2 validate_args Name, \%args -> 1 | ERROR + has 'size' => ( + is => 'ro', + lazy => 1, + builder => '_build_size', + clearer => 'clear_size', + predicate => 'has_size', + ); -Checks that the arguments to create the attribute (ie those specified by -C) are valid. +=back + +=head2 C<< verify_against_type_constraint(Item) -> TRUE | ERROR >> + +Checks that the given value passes this attribute's type constraint. Returns C +on success, otherwise Ces. -=head2 clone_parent OwnerClass, AttributeName, %args -> Mouse::Meta::Attribute +=head2 C<< clone_and_inherit_options(options) -> Mouse::Meta::Attribute >> Creates a new attribute in OwnerClass, inheriting options from parent classes. Accessors and helper methods are installed. Some error checking is done. -=head2 get_parent_args OwnerClass, AttributeName -> Hash +=head1 SEE ALSO -Returns the options that the parent class of C used for attribute -C. +L =cut diff --git a/lib/Mouse/Meta/Class.pm b/lib/Mouse/Meta/Class.pm index cb02454..51a496f 100644 --- a/lib/Mouse/Meta/Class.pm +++ b/lib/Mouse/Meta/Class.pm @@ -369,7 +369,7 @@ __END__ =head1 NAME -Mouse::Meta::Class - hook into the Mouse MOP +Mouse::Meta::Class - The Mouse class metaclass =head1 METHODS @@ -428,11 +428,9 @@ Create a new instance. Clones the given C which must be an instance governed by this metaclass. -=head1 BUGS +=head1 SEE ALSO -All complex software has bugs lurking in it, and this module is no -exception. If you find a bug please either email me, or add the bug -to cpan-RT. +L =cut diff --git a/lib/Mouse/Meta/Method.pm b/lib/Mouse/Meta/Method.pm index 9c0b5e3..cbe349a 100755 --- a/lib/Mouse/Meta/Method.pm +++ b/lib/Mouse/Meta/Method.pm @@ -23,3 +23,13 @@ sub package_name{ $_[0]->{package} } 1; __END__ + +=head1 NAME + +Mouse::Meta::Method - A Mouse Method metaclass + +=head1 SEE ALSO + +L + +=cut diff --git a/lib/Mouse/Meta/Module.pm b/lib/Mouse/Meta/Module.pm index 0bebd8f..f71c60c 100755 --- a/lib/Mouse/Meta/Module.pm +++ b/lib/Mouse/Meta/Module.pm @@ -299,7 +299,7 @@ __END__ =head1 NAME -Mouse::Meta::Module - Common base class for Mouse::Meta::Class and Mouse::Meta::Role +Mouse::Meta::Module - The base class for Mouse::Meta::Class and Mouse::Meta::Role =cut diff --git a/lib/Mouse/Meta/Role.pm b/lib/Mouse/Meta/Role.pm index 6deb58c..8ca0759 100644 --- a/lib/Mouse/Meta/Role.pm +++ b/lib/Mouse/Meta/Role.pm @@ -416,3 +416,14 @@ sub does_role { 1; +__END__ + +=head1 NAME + +Mouse::Meta::Role - The Mouse Role metaclass + +=head1 SEE ALSO + +L + +=cut diff --git a/lib/Mouse/Meta/Role/Method.pm b/lib/Mouse/Meta/Role/Method.pm index 1d3d0a0..8702e7c 100755 --- a/lib/Mouse/Meta/Role/Method.pm +++ b/lib/Mouse/Meta/Role/Method.pm @@ -8,3 +8,13 @@ use base qw(Mouse::Meta::Method); __END__ +=head1 NAME + +Mouse::Meta::Role::Method - A Mouse Method metaclass for Roles + +=head1 SEE ALSO + +L + +=cut + diff --git a/lib/Mouse/Meta/TypeConstraint.pm b/lib/Mouse/Meta/TypeConstraint.pm index 3405a18..13b4495 100644 --- a/lib/Mouse/Meta/TypeConstraint.pm +++ b/lib/Mouse/Meta/TypeConstraint.pm @@ -84,7 +84,7 @@ __END__ =head1 NAME -Mouse::Meta::TypeConstraint - The Mouse Type Constraint Metaclass +Mouse::Meta::TypeConstraint - The Mouse Type Constraint metaclass =head1 DESCRIPTION @@ -106,5 +106,9 @@ Don't use this. =back +=head1 SEE ALSO + +L + =cut diff --git a/lib/Mouse/Object.pm b/lib/Mouse/Object.pm index 89bd8ca..4abc0d6 100644 --- a/lib/Mouse/Object.pm +++ b/lib/Mouse/Object.pm @@ -76,43 +76,42 @@ Mouse::Object - we don't need to steenkin' constructor =head1 METHODS -=head2 new arguments -> object +=head2 C<< new arguments -> Object >> -Instantiates a new Mouse::Object. This is obviously intended for subclasses. +Instantiates a new C. This is obviously intended for subclasses. -=head2 BUILDALL \%args +=head2 C<< BUILDARGS(@args) -> HashRef >> -Calls L on each class in the class hierarchy. This is called at the -end of L. +Lets you override the arguments that C takes. Return a hashref of +parameters. -=head2 BUILD \%args +=head2 C<< BUILDALL \%args >> -You may put any business logic initialization in BUILD methods. You don't -need to redispatch or return any specific value. +Calls C on each class in the class hierarchy. This is called at the +end of C. -=head2 BUILDARGS +=head2 C<< BUILD \%args >> -Lets you override the arguments that C takes. Return a hashref of -parameters. +You may put any business logic initialization in BUILD methods. You don't +need to redispatch or return any specific value. -=head2 DEMOLISHALL +=head2 C<< DEMOLISHALL >> -Calls L on each class in the class hierarchy. This is called at -L time. +Calls C on each class in the class hierarchy. This is called at +C time. -=head2 DEMOLISH +=head2 C<< DEMOLISH >> You may put any business logic deinitialization in DEMOLISH methods. You don't need to redispatch or return any specific value. -=head2 does $role_name +=head2 C<< does ($role_name) -> Bool >> -This will check if the invocant's class "does" a given C<$role_name>. +This will check if the invocant's class B a given C<$role_name>. This is similar to "isa" for object, but it checks the roles instead. - -=head2 B +=head2 C< Str >> From the Moose POD: @@ -125,6 +124,9 @@ From the Moose POD: The implementation was lifted directly from Moose::Object. -=cut +=head1 SEE ALSO + +L +=cut diff --git a/lib/Mouse/Role.pm b/lib/Mouse/Role.pm index 59cccd2..0059eb6 100644 --- a/lib/Mouse/Role.pm +++ b/lib/Mouse/Role.pm @@ -161,59 +161,60 @@ __END__ =head1 NAME -Mouse::Role - define a role in Mouse +Mouse::Role - The Mouse Role + +=head1 SYNOPSIS + + package MyRole; + use Mouse::Role; =head1 KEYWORDS -=head2 meta -> Mouse::Meta::Role +=head2 C<< meta -> Mouse::Meta::Role >> Returns this role's metaclass instance. -=head2 before (method|methods) => Code +=head2 C<< before (method|methods) -> CodeRef >> -Sets up a "before" method modifier. See L or +Sets up a B method modifier. See L or L. -=head2 after (method|methods) => Code +=head2 C<< after (method|methods) => CodeRef >> -Sets up an "after" method modifier. See L or +Sets up an B method modifier. See L or L. -=head2 around (method|methods) => Code +=head2 C<< around (method|methods) => CodeRef >> -Sets up an "around" method modifier. See L or +Sets up an B method modifier. See L or L. -=over 4 - -=item B +=head2 C -Sets up the "super" keyword. See L. +Sets up the B keyword. See L. -=item B +=head2 C<< override method => CodeRef >> -Sets up an "override" method modifier. See L. +Sets up an B method modifier. See L. -=item B +=head2 C -This is not supported and emits an error. See L. +This is not supported in roles and emits an error. See L. -=item B +=head2 C<< augment method => CodeRef >> -This is not supported and emits an error. See L. +This is not supported in roles and emits an error. See L. -=back - -=head2 has (name|names) => parameters +=head2 C<< has (name|names) => parameters >> Sets up an attribute (or if passed an arrayref of names, multiple attributes) to this role. See L. -=head2 confess error -> BOOM +=head2 C<< confess(error) -> BOOM >> L for your convenience. -=head2 blessed value -> ClassName | undef +=head2 C<< blessed(value) -> ClassName | undef >> L for your convenience. @@ -225,8 +226,12 @@ Importing Mouse::Role will give you sugar. =head2 unimport -Please unimport Mouse (C) so that if someone calls one of the +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. +=head1 SEE ALSO + +L + =cut diff --git a/lib/Mouse/Util.pm b/lib/Mouse/Util.pm index 01a9efc..0e4d865 100644 --- a/lib/Mouse/Util.pm +++ b/lib/Mouse/Util.pm @@ -331,9 +331,17 @@ Mouse::Util - features, with or without their dependencies =head2 Class::MOP -=head3 C +=head2 C<< is_class_loaded(ClassName) -> Bool >> -=head3 C +Returns whether C is actually loaded or not. It uses a heuristic which +involves checking for the existence of C<$VERSION>, C<@ISA>, and any +locally-defined method. + +=head3 C<< load_class(ClassName) >> + +This will load a given C (or die if it's not loadable). +This function can be used in place of tricks like +C or using C. =head2 MRO::Compat @@ -353,5 +361,15 @@ C =back +=head1 SEE ALSO + +L + +L + +L + +L + =cut diff --git a/lib/Mouse/Util/TypeConstraints.pm b/lib/Mouse/Util/TypeConstraints.pm index dbd639e..dcad15c 100644 --- a/lib/Mouse/Util/TypeConstraints.pm +++ b/lib/Mouse/Util/TypeConstraints.pm @@ -582,21 +582,31 @@ Returns the simple type constraints that Mouse understands. =over 4 -=item B as 'Parent' => where { } ...> +=item C<< subtype 'Name' => as 'Parent' => where { } ... -> Mouse::Meta::TypeConstraint >> -=item B where { } ...> +=item C<< subtype as 'Parent' => where { } ... -> Mouse::Meta::TypeConstraint >> -=item B +=item C<< class_type ($class, ?$options) -> Mouse::Meta::TypeConstraint >> -=item B +=item C<< role_type ($role, ?$options) -> Mouse::Meta::TypeConstraint >> -=item B +=item C<< enum (\@values) -> Mouse::Meta::TypeConstraint >> + +=back + +=over 4 + +=item C<< find_type_constraint(Type) -> Mouse::Meta::TypeConstraint >> =back =head1 THANKS -Much of this documentation was taken from L +Much of this documentation was taken from C + +=head1 SEE ALSO + +L =cut diff --git a/lib/Squirrel.pm b/lib/Squirrel.pm index f73f867..27579db 100644 --- a/lib/Squirrel.pm +++ b/lib/Squirrel.pm @@ -52,7 +52,7 @@ __END__ =head1 NAME -Squirrel - Use L, unless L is already loaded. +Squirrel - Use L, unless L is already loaded. (DEPRECATED) =head1 SYNOPSIS @@ -64,12 +64,12 @@ Squirrel - Use L, unless L is already loaded. =head1 DEPRECATION -L is deprecated. L provides the same functionality, +C is deprecated. C provides the same functionality, but better. :) =head1 DESCRIPTION -L and L are TEH BEST FRENDS, but if L isn't there +L and L are THE BEST FRIENDS, but if L isn't there L will hang out with L as well. When your own code doesn't actually care whether or not you use L or @@ -79,6 +79,10 @@ This lets you run with minimal dependencies and have a faster startup, but if L is already in use you get all the benefits of using that (transformability, introspection, more opportunities for code reuse, etc). +=head1 SEE ALSO + +L + =cut diff --git a/lib/Squirrel/Role.pm b/lib/Squirrel/Role.pm index 4a0941b..640c1c6 100644 --- a/lib/Squirrel/Role.pm +++ b/lib/Squirrel/Role.pm @@ -24,3 +24,11 @@ sub _choose_backend { 1; +__END__ + +=head1 NAME + +Squirrel::Role - Use Mouse::Role, unless MooseRole is already loaded. (DEPRECATED) + +=cut + diff --git a/lib/ouse.pm b/lib/ouse.pm index a237ee8..3026ced 100644 --- a/lib/ouse.pm +++ b/lib/ouse.pm @@ -37,18 +37,18 @@ ouse - syntactic sugar to make Mouse one-liners easier =head1 DESCRIPTION -ouse.pm is a simple source filter that adds C +F is a simple source filter that adds C to the beginning of your script and was entirely created because typing -perl -e'package Foo; use Mouse; ...' was annoying me... especially after +perl C<< -e'package Foo; use Mouse; ...' >> was annoying me... especially after getting used to having C<-Moose> for Moose. =head1 INTERFACE -ouse provides exactly one method and it's automically called by perl: +C provides exactly one method and it is automatically called by perl: =over 4 -=item B +=item C<< oose->import() >>> Pass a package name to import to be used by the source filter. @@ -62,11 +62,9 @@ You will need L and eventually L None reported. But it is a source filter and might have issues there. -=head1 BUGS +=head1 SEE ALSO -All complex software has bugs lurking in it, and this module is no -exception. If you find a bug please either email me, or add the bug -to cpan-RT. +L for C<< perl -Moose -e '...' >> =head1 AUTHOR diff --git a/xt/99_pod.t b/xt/99_pod.t deleted file mode 100644 index 437887a..0000000 --- a/xt/99_pod.t +++ /dev/null @@ -1,4 +0,0 @@ -use Test::More; -eval "use Test::Pod 1.00"; -plan skip_all => "Test::Pod 1.00 required for testing POD" if $@; -all_pod_files_ok();