From: Marcel Grünauer Date: Tue, 3 Feb 2009 23:56:59 +0000 (+0000) Subject: typo and style fixes for Moose::Manual documents X-Git-Tag: 0.67~3 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=0c39debe42b82fda7f19f3053903650ac7920a65;p=gitmo%2FMoose.git typo and style fixes for Moose::Manual documents --- diff --git a/lib/Moose/Manual/Attributes.pod b/lib/Moose/Manual/Attributes.pod index 493a165..3740c11 100644 --- a/lib/Moose/Manual/Attributes.pod +++ b/lib/Moose/Manual/Attributes.pod @@ -303,7 +303,7 @@ This is the same as specifying all of these options: predicate => 'has_size', ); -If your attribute name starts with an underscore (_), then the clearer +If your attribute name starts with an underscore (C<_>), then the clearer and predicate will as well: has '_size' => ( @@ -351,7 +351,7 @@ Both of these goals can be accomplished with the C option: init_arg => 'size', ); -Now we have an attribute named bigness, but we pass C to the +Now we have an attribute named "bigness", but we pass C to the constructor. Even more useful is the ability to disable setting an attribute via @@ -411,7 +411,7 @@ Attributes can be restricted to only accept certain types: isa => 'Str', ); -This says that the first_name attribute must be a string. +This says that the C attribute must be a string. Moose also provides a shortcut for specifying that an attribute only accepts objects that do a certain role: @@ -426,7 +426,7 @@ discussion of Moose's type system. =head2 Delegation -Attributes can define methods which simple delegate to their values: +Attributes can define methods which simply delegate to their values: has 'hair_color' => ( is => 'rw', @@ -458,7 +458,7 @@ traits for the attribute: ); In this case, the metaclass C really refers to -C. +L. You can also apply one or more traits to an attribute: @@ -514,7 +514,7 @@ The options that can be overridden in a subclass are: =back To override an attribute, you simply prepend its name with a plus sign -(+): +(C<+>): package LazyPerson; @@ -567,9 +567,9 @@ returned from the reader method: my %map = $object->mapping; This option only works if your attribute is explicitly typed as an -ArrayRef or HashRef. +C or C. -However, we recommend that you use C for +However, we recommend that you use L for these types of attributes, which gives you much more control over how they are accessed and manipulated. @@ -579,7 +579,7 @@ Moose provides an attribute option called C. This is similar to C, except that it is I called during object construction. -This option is inherited from C, but we recommend that you +This option is inherited from L, but we recommend that you use a C (which is Moose-only) instead. =head1 AUTHOR diff --git a/lib/Moose/Manual/BestPractices.pod b/lib/Moose/Manual/BestPractices.pod index d36db1e..1814b1a 100644 --- a/lib/Moose/Manual/BestPractices.pod +++ b/lib/Moose/Manual/BestPractices.pod @@ -32,7 +32,7 @@ Moose sugar and making your class immutable. 1; -The "no Moose" bit is simply good code hygiene, and making classes +The C bit is simply good code hygiene, and making classes immutable speeds up a lot of things, most notably object construction. =head2 Always call SUPER::BUILDARGS @@ -45,11 +45,11 @@ The default C method in L handles both a list and hashref of named parameters correctly, and also checks for a I single argument. -=head2 Don't Use the initializer Feature +=head2 Don't Use the C Feature Don't know what we're talking about? That's fine. -=head2 Use builder Instead of default Most of the Time. +=head2 Use C Instead of C Most of the Time. Builders can be inherited, they have explicit names, and they're just plain cleaner. @@ -59,14 +59,14 @@ I when the default is simply an empty reference of some sort. Also, keep your builder methods private. -=head2 Use lazy_build +=head2 Use C Lazy is good, and often solves initialization ordering problems. It's also good for deferring work that may never have to be done. If you're going to be lazy, use I to save yourself some typing and standardize names. -=head2 Consider Keeping clearers & predicates Private +=head2 Consider Keeping Clearers and Predicates Private Does everyone I need to be able to clear an attribute? Probably not. Don't expose this functionality outside your class @@ -75,7 +75,7 @@ by default. Predicates are less problematic, but there's no reason to make your public API bigger than it has to be. -=head2 Default to read-only, and Consider Keeping writers Private +=head2 Default to read-only, and Consider Keeping Writers Private Making attributes mutable just means more complexity to account for in your program. The alternative to mutable state is to encourage users @@ -91,11 +91,11 @@ Down this path lies great confusion. If the attribute is an object itself, at least make sure that it has the same interface as the type of object in the parent class. -=head2 Use MooseX::AttributeHelpers Instead of auto_deref +=head2 Use L Instead of C The C feature is a bit troublesome. Directly exposing a complex attribute is ugly. Instead, consider using -C to define an API that exposes those pieces +L to define an API that exposes those pieces of functionality that need exposing. Then you can expose just the functionality that you want. diff --git a/lib/Moose/Manual/Construction.pod b/lib/Moose/Manual/Construction.pod index ca9386f..1a17e64 100644 --- a/lib/Moose/Manual/Construction.pod +++ b/lib/Moose/Manual/Construction.pod @@ -9,7 +9,7 @@ Moose::Manual::Construction - Object construction (and destruction) with Moose B method for your classes!> When you C in your class, you will become a subclass of -C, which provides a C method for you. If you +L, which provides a C method for you. If you follow our recommendations in L and make your class immutable, then you actually get a class-specific C method "inlined" in your class. @@ -62,7 +62,7 @@ accommodate this calling style: } Note the call to C. This will call the default -C in C. This method handles distinguishing +C in L. This method handles distinguishing between a hash reference and a plain hash for you. =head2 BUILD diff --git a/lib/Moose/Manual/MooseX.pod b/lib/Moose/Manual/MooseX.pod index b444eb3..192133c 100644 --- a/lib/Moose/Manual/MooseX.pod +++ b/lib/Moose/Manual/MooseX.pod @@ -52,7 +52,7 @@ well-named, easy to use methods. =head1 MooseX::StrictConstructor By default, Moose lets you pass any old junk into a class's -constructor. If you load C, your class will +constructor. If you load L, your class will throw an error if it sees something it doesn't recognize; package User; @@ -65,15 +65,15 @@ throw an error if it sees something it doesn't recognize; User->new( name => 'Bob', emali => 'bob@example.com' ); -With C, that typo ("emali") will cause a +With L, that typo ("emali") will cause a runtime error. With plain old Moose, the "emali" attribute would be silently ignored. =head1 MooseX::Params::Validate -We have high hopes for the future of C and -C. However, for now we recommend the decidedly more -clunky (but also faster and simpler) C. This +We have high hopes for the future of L and +L. However, for now we recommend the decidedly more +clunky (but also faster and simpler) L. This module lets you apply Moose types and coercions to any method arguments. @@ -131,7 +131,7 @@ From the command line, someone can execute the script: =head1 MooseX::Singleton To be honest, using a singleton is often a hack, but it sure is a -handy hack. C lets you have a Moose class that's a +handy hack. L lets you have a Moose class that's a singleton: package Config; @@ -180,7 +180,7 @@ bareword names, even if the type definitions differ. =head2 MooseX::Types::Structured -This extension builds on top of C to let you declare +This extension builds on top of L to let you declare complex data structure types. use MooseX::Types -declare => [ qw( Name Color ) ]; diff --git a/lib/Moose/Manual/Roles.pod b/lib/Moose/Manual/Roles.pod index 1745cdc..00eb954 100644 --- a/lib/Moose/Manual/Roles.pod +++ b/lib/Moose/Manual/Roles.pod @@ -47,7 +47,7 @@ Creating a role looks a lot like creating a Moose class: $self->is_broken(1); } -Except for our use of C, this looks just like a class +Except for our use of L, this looks just like a class definition with Moose. However, this is not a class, and it cannot be instantiated. diff --git a/lib/Moose/Manual/Types.pod b/lib/Moose/Manual/Types.pod index 6fa9753..e9489ed 100644 --- a/lib/Moose/Manual/Types.pod +++ b/lib/Moose/Manual/Types.pod @@ -118,7 +118,7 @@ that the name is a class: isa => 'ArrayRef[DateTime]', ); -Moose will assume that "DateTime" is a class name in both of these +Moose will assume that C is a class name in both of these instances. =head1 SUBTYPES @@ -128,7 +128,7 @@ C for example. A subtype is defined in terms of a parent type and a constraint. Any constraints defined by the parent(s) will be checked first, and then -the the subtype's . A value must pass I of these checks to be +the the subtype's. A value must pass I of these checks to be valid for the subtype. Typically, a subtype takes the parent's constraint and makes it more @@ -185,7 +185,7 @@ class names are I valid type names! Using something else, like a period, makes it clear that "MyApp::User" is a class and "MyApp.Type.PositiveInt" is a Moose type defined by your application. -The C module lets you create bareword aliases to longer +The L module lets you create bareword aliases to longer names and also automatically namespaces all the types you define. =head1 COERCION @@ -366,7 +366,7 @@ Moose does not provide any means of validating method parameters. However, there are several MooseX extensions on CPAN which let you do this. -The simplest and least sugary is C. This +The simplest and least sugary is L. This lets you validate a set of named parameters using Moose types: use Moose; @@ -381,11 +381,11 @@ lets you validate a set of named parameters using Moose types: ... } -C also supports coercions. +L also supports coercions. There are several more powerful extensions that support method parameter validation using Moose types, including -C, which gives you a full-blown C +L, which gives you a full-blown C keyword. method morning (Str $name) {