From: Jesse Luehrs Date: Sun, 29 Mar 2009 07:02:55 +0000 (-0500) Subject: typo fixes for the documentation section (other than the recipes) X-Git-Tag: 0.73_01~17 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=dab940632264ba728cdd882436a2c972f001fecf;p=gitmo%2FMoose.git typo fixes for the documentation section (other than the recipes) --- diff --git a/lib/Moose/Cookbook.pod b/lib/Moose/Cookbook.pod index d6d1b8a..dab5760 100644 --- a/lib/Moose/Cookbook.pod +++ b/lib/Moose/Cookbook.pod @@ -18,7 +18,7 @@ explains Moose concepts without being too code-heavy. =head2 Basic Moose -These recipes will give you a good idea of what Moose is capable, +These recipes will give you a good idea of what Moose is capable of, starting with simple attribute declaration, and moving on to more powerful features like laziness, types, type coercion, method modifiers, and more. @@ -27,7 +27,7 @@ modifiers, and more. =item L - The (always classic) B example -A simple Moose-based class. Demonstrated Moose attributes and subclassing. +A simple Moose-based class. Demonstrates Moose attributes and subclassing. =item L - A simple B example @@ -97,7 +97,7 @@ subclassing. =item L - Advanced Role Composition - method exclusion and aliasing Sometimes you just want to include part of a role in your -class. Sometimes you want the whole role but one if its methods +class. Sometimes you want the whole role but one of its methods conflicts with one in your class. With method exclusion and aliasing, you can work around these problems. @@ -110,7 +110,7 @@ In this recipe, we apply a role to an existing object instance. =head2 Meta Moose These recipes show you how to write your own meta classes, which lets -you extend the object system provide by Moose. +you extend the object system provided by Moose. =over 4 @@ -182,9 +182,9 @@ if you plan to write your own C module. =item L - Moose extension overview -There are quite a number of ways to extend Moose. This recipe explains -provides an overview of each method, and provides recommendations for -when each is appropriate. +There are quite a few ways to extend Moose. This recipe provides an +overview of each method, and provides recommendations for when each is +appropriate. =item L - Providing a base object class role diff --git a/lib/Moose/Cookbook/FAQ.pod b/lib/Moose/Cookbook/FAQ.pod index feec98b..9a54c6a 100644 --- a/lib/Moose/Cookbook/FAQ.pod +++ b/lib/Moose/Cookbook/FAQ.pod @@ -73,7 +73,7 @@ Perl 6. Every C method in your inheritance chain is called (in the correct order) immediately after the instance is constructed. This allows you to ensure that all your superclasses are initialized properly as well. This is the best approach to take (when possible) -because it makes sub classing your class much easier. +because it makes subclassing your class much easier. If you need to affect the constructor's parameters prior to the instance actually being constructed, you have a number of options. @@ -278,10 +278,10 @@ release. =head3 How do I get Moose to call BUILD in all my composed roles? -See L and specifically the B question in the B section. +See L and specifically the B question in the B section. -=head3 What are Traits, and how are they different to Roles? +=head3 What are Traits, and how are they different from Roles? In Moose, a trait is almost exactly the same thing as a role, except that traits typically register themselves, which allows you to refer diff --git a/lib/Moose/Cookbook/WTF.pod b/lib/Moose/Cookbook/WTF.pod index 4b07bcd..529409e 100644 --- a/lib/Moose/Cookbook/WTF.pod +++ b/lib/Moose/Cookbook/WTF.pod @@ -36,7 +36,7 @@ L. =head2 Constructors & Immutability -=head3 I made my class immutable, but C it is still slow! +=head3 I made my class immutable, but C is still slow! Do you have a custom C method in your class? Moose will not overwrite your custom C method, you would @@ -48,7 +48,7 @@ the attribute declaration. around) C is not being called? Making a I, I or I wrap around the -C method, will actually create a C method within +C method will actually create a C method within your class. This will prevent Moose from creating one itself when you make the class immutable. @@ -65,18 +65,18 @@ when what you really want to say is: has 'foo' => (isa => 'Bar', is => 'rw'); -The reason this is so, is because it is a perfectly valid use +The reason this is so is because it is a perfectly valid use case to I have an accessor. The simplest one is that you -want to write your own. If Moose created on automatically, then +want to write your own. If Moose created one automatically, then because of the order in which classes are constructed, Moose would overwrite your custom accessor. You wouldn't want that would you? =head2 Method Modifiers -=head3 How come I can't change C<@_> in a C modifier? +=head3 Why can't I change C<@_> in a C modifier? -The C modifier simply is called I the main method. +The C modifier is called I the main method. Its return values are simply ignored, and are B passed onto the main method body. @@ -91,7 +91,7 @@ modifier instead. Here is some sample code: $next->($self, reverse(@args)); }; -=head3 How come I can't see return values in an C modifier? +=head3 Why can't I see return values in an C modifier? As with the C modifier, the C modifier is simply called I the main method. It is passed the original contents @@ -134,7 +134,7 @@ See L. =head2 Roles -=head3 How come BUILD is not called for my composed roles? +=head3 Why is BUILD not called for my composed roles? BUILD is never called in composed roles. The primary reason is that roles are B order sensitive. Roles are composed in such a way @@ -158,13 +158,13 @@ L) =item * -Use attributes triggers, which fire after an attribute it set, to facilitate -initialization. These are described in the L docs and examples can be +Use attribute triggers, which fire after an attribute is set, to facilitate +initialization. These are described in the L docs, and examples can be found in the test suite. =back -In general, roles should not I initialization, they should either +In general, roles should not I initialization; they should either provide sane defaults or should be documented as needing specific initialization. One such way to "document" this is to have a separate attribute initializer which is required for the role. Here is an example of diff --git a/lib/Moose/Manual.pod b/lib/Moose/Manual.pod index e19d9a8..543f7a5 100644 --- a/lib/Moose/Manual.pod +++ b/lib/Moose/Manual.pod @@ -22,7 +22,7 @@ With Moose, you can concentrate on the I structure of your classes, focusing on "what" rather than "how". A class definition with Moose reads like a list of very concise English sentences. -Moose is built in top of C, a meta-object protocol (aka +Moose is built on top of C, a meta-object protocol (aka MOP). Using the MOP, Moose provides complete introspection for all Moose-using classes. This means you can ask classes about their attributes, parents, children, methods, etc., all using a well-defined @@ -123,7 +123,7 @@ features! =item L -Delegation is a powerful way to make use of attribute which are +Delegation is a powerful way to make use of attributes which are themselves objects. =item L @@ -156,7 +156,8 @@ children, methods, attributes, etc. =item L -This document shows a few of the most useful Moose extensions on CPAN. +This document describes a few of the most useful Moose extensions on +CPAN. =item L @@ -177,7 +178,7 @@ changes to Moose. =head1 JUSTIFICATION -If you're still still asking yourself "Why do I need this?", then this +If you're still asking yourself "Why do I need this?", then this section is for you. =over 4 @@ -210,8 +211,9 @@ production with little or no issue now for years. We consider it highly stable and we are committed to keeping it stable. Of course, in the end, you need to make this call yourself. If you -have any questions or concerns, please feel free to email Stevan, the -moose@perl.org list, or just stop by irc.perl.org#moose and ask away. +have any questions or concerns, please feel free to email Stevan or +the moose@perl.org list, or just stop by irc.perl.org#moose and ask +away. =item Is Moose just Perl 6 in Perl 5? diff --git a/lib/Moose/Manual/Attributes.pod b/lib/Moose/Manual/Attributes.pod index 7a2963b..4ee76e5 100644 --- a/lib/Moose/Manual/Attributes.pod +++ b/lib/Moose/Manual/Attributes.pod @@ -36,10 +36,10 @@ Use the C function to declare an attribute: This says that all C objects have an optional read-write "first_name" attribute. -=head2 Read-write Vs read-only +=head2 Read-write vs. read-only The options passed to C define the properties of the -attribute. There are a many options, but in the simplest form you just +attribute. There are many options, but in the simplest form you just need to set C, which can be either C (read-write) or C (read-only). @@ -67,12 +67,12 @@ particularly handy when you'd like an attribute to be publicly readable, but only privately settable. For example: has 'weight' => ( - is => 'rw', + is => 'ro', writer => '_set_weight', ); -This might be useful if weight is calculated based on other methods, -for example every time the C method is called, we might adjust +This might be useful if weight is calculated based on other methods. +For example, every time the C method is called, we might adjust weight. This lets us hide the implementation details of weight changes, but still provide the weight value to users of the class. @@ -91,7 +91,7 @@ C methods: If you're thinking that doing this over and over would be insanely tedious, you're right! Fortunately, Moose provides a powerful -extension system that lets override the default naming +extension system that lets you override the default naming conventions. See L for more details. =head2 Predicate and clearer methods @@ -102,8 +102,9 @@ you want to access this information, you must define clearer and predicate methods for an attribute. A predicate method tells you whether or not a given attribute is -currently set. Note an attribute can be explicitly set to C or -some other false value, but the predicate will return true. +currently set. Note that an attribute can be explicitly set to +C or some other false value, but the predicate will return +true. The clearer method unsets the attribute. This is I the same as setting the value to C, but you can only distinguish @@ -459,8 +460,8 @@ The trigger is called I the value is set. This differs from an after method modifier in two ways. First, a trigger is only called when the attribute is set, as opposed to whenever the accessor method is called (for reading or -writing). Second, it is also called if the when an attribute's value -is passed to the constructor. +writing). Second, it is also called when an attribute's value is +passed to the constructor. However, triggers are I called when an attribute is populated from a C or C @@ -599,9 +600,9 @@ of an inherited attribute. =head1 MORE ON ATTRIBUTES Moose attributes are a big topic, and this document glosses over a few -aspects of their aspects. We recommend that you read the -L and L documents to -get a more complete understanding of attribute features. +aspects. We recommend that you read the L +and L documents to get a more complete +understanding of attribute features. =head1 A FEW MORE OPTIONS diff --git a/lib/Moose/Manual/BestPractices.pod b/lib/Moose/Manual/BestPractices.pod index 514ee4a..b6ea608 100644 --- a/lib/Moose/Manual/BestPractices.pod +++ b/lib/Moose/Manual/BestPractices.pod @@ -207,7 +207,7 @@ will be faster when immutabilized. Many of these practices also help get the most out of meta programming. If you used an overridden C to do type coercion by hand, rather than defining a real coercion, there is no introspectable -metadata. This sort of thing is particularly problematic MooseX +metadata. This sort of thing is particularly problematic for MooseX extensions which rely on introspection to do the right thing. =head1 AUTHOR diff --git a/lib/Moose/Manual/Classes.pod b/lib/Moose/Manual/Classes.pod index f2cd397..7183de9 100644 --- a/lib/Moose/Manual/Classes.pod +++ b/lib/Moose/Manual/Classes.pod @@ -31,12 +31,12 @@ example, you might define an attribute ... Attributes are described in the L documentation. -Loading Moose also turns enables C and C pragmas in -your class. +Loading Moose also enables C and C pragmas in your +class. When you load Moose, your class will become a subclass of L. The L class provides a default -constructor, destructor, as well as object construction helper +constructor and destructor, as well as object construction helper methods. You can read more about this in the L document. @@ -107,8 +107,8 @@ class's metaclass object. If you override C in your class, then the immutabilization code will not be able to provide an optimized constructor for your -class. Instead, you should use C method, which will be called -from the inlined constructor. +class. Instead, you should use a C method, which will be +called from the inlined constructor. Alternately, if you really need to provide a different C, you can also provide your own immutabilization method. Doing so requires diff --git a/lib/Moose/Manual/Concepts.pod b/lib/Moose/Manual/Concepts.pod index 70cac00..33c8f4e 100644 --- a/lib/Moose/Manual/Concepts.pod +++ b/lib/Moose/Manual/Concepts.pod @@ -67,8 +67,8 @@ method names, B, a default value, and more. Attributes I methods, but defining them causes various accessor methods to be created. At a minimum, a normal attribute will -always have a reader accessor method. Many attributes also other -methods such as a writer method, clearer method, and predicate method +always have a reader accessor method. Many attributes also have other +methods, such as a writer method, clearer method, and predicate method ("has it been set?"). An attribute may also define B, which will create @@ -177,7 +177,7 @@ define types for attributes. Moose has a set of built-in types based on what Perl provides, such as C, C, C, C, etc. In addition, every class name in your application can also be used as -a type name. We saw an example using C earlier. +a type name. Finally, you can define your own types, either as subtypes or entirely new types, with their own constraints. For example, you could define a @@ -355,9 +355,10 @@ extensions. So you're sold on Moose. Time to learn how to really use it. -If you want to see how Moose would translate directly old school Perl -5 OO code, check out L. This might be helpful for -quickly wrapping your brain around some aspects of "the Moose way". +If you want to see how Moose would translate directly into old school +Perl 5 OO code, check out L. This might be +helpful for quickly wrapping your brain around some aspects of "the +Moose way". Obviously, the next thing to read is the rest of the L. diff --git a/lib/Moose/Manual/Construction.pod b/lib/Moose/Manual/Construction.pod index 9f35a9d..de8d983 100644 --- a/lib/Moose/Manual/Construction.pod +++ b/lib/Moose/Manual/Construction.pod @@ -68,10 +68,10 @@ between a hash reference and a plain hash for you. =head2 BUILD The C method is called I an object is created. There are -ways to use a C method. One of the most common is to check that -the object state is valid. While we can validate individual attributes -through the use of types, we can't validate the state of a whole -object that way. +several ways to use a C method. One of the most common is to +check that the object state is valid. While we can validate individual +attributes through the use of types, we can't validate the state of a +whole object that way. sub BUILD { my $self = shift; diff --git a/lib/Moose/Manual/MOP.pod b/lib/Moose/Manual/MOP.pod index 1cf433e..e1c9c4d 100644 --- a/lib/Moose/Manual/MOP.pod +++ b/lib/Moose/Manual/MOP.pod @@ -24,9 +24,9 @@ method that you're looking for is defined in a C class, rather than Moose itself. The MOP provides more than just I introspection. It also -lets you add attributes, method, apply roles, and much more. In fact, -all of the declarative Moose sugar is simply a thin layer on top of -the MOP API. +lets you add attributes and methods, apply roles, and much more. In +fact, all of the declarative Moose sugar is simply a thin layer on top +of the MOP API. If you want to write Moose extensions, you'll need to learn some of the MOP API. The introspection methods are also handy if you want to @@ -80,7 +80,7 @@ and its parents. You can also get a list of methods: for my $method ( $meta->get_all_methods ) { - print $meth->fully_qualified_name, "\n"; + print $method->fully_qualified_name, "\n"; } Now we're looping over a list of L objects. Note @@ -137,7 +137,7 @@ being run before you make a class immutable. =head1 GOING FURTHER -If you're interested in extending moose, we recommend reading all of +If you're interested in extending Moose, we recommend reading all of the "Meta" and "Extending" recipes in the L. Those recipes show various practical applications of the MOP. diff --git a/lib/Moose/Manual/MethodModifiers.pod b/lib/Moose/Manual/MethodModifiers.pod index 3325dab..2a69b25 100644 --- a/lib/Moose/Manual/MethodModifiers.pod +++ b/lib/Moose/Manual/MethodModifiers.pod @@ -67,14 +67,14 @@ Method modifiers have many uses. One very common use is in roles. This lets roles alter the behavior of methods in the classes that use them. See L for more information about roles. -Most of the modifiers are most useful in roles, so some of the -examples below are a bit artificial. They're intended to give you an -idea of how modifiers work, but may not be the most natural usage. +Since modifiers are mostly useful in roles, some of the examples below +are a bit artificial. They're intended to give you an idea of how +modifiers work, but may not be the most natural usage. =head1 BEFORE, AFTER, AND AROUND -Method modifiers can also be used to add behavior to a method that -Moose generates for you, such as an attribute accessor: +Method modifiers can be used to add behavior to a method that Moose +generates for you, such as an attribute accessor: has 'size' => ( is => 'rw' ); @@ -109,8 +109,8 @@ ignored. An around modifier is a bit more powerful than either a before or after modifier. It can modify the arguments being passed to the original method, and you can even decide to simply not call the -original method at all. Finally, you can modify the return value with -an around modifier. +original method at all. You can also modify the return value with an +around modifier. An around modifier receives the original method as its first argument, I the object, and finally any arguments passed to the method. diff --git a/lib/Moose/Manual/MooseX.pod b/lib/Moose/Manual/MooseX.pod index cb575d2..607bf35 100644 --- a/lib/Moose/Manual/MooseX.pod +++ b/lib/Moose/Manual/MooseX.pod @@ -12,7 +12,7 @@ add new features, and generally customize your Moose. Writing your own extensions does require a good understanding of the meta-model. You can start learning about this with the -L docs. There are also several extensions recipes +L docs. There are also several extension recipes in the L. Explaining how to write extensions is beyond the scope of this diff --git a/lib/Moose/Manual/Roles.pod b/lib/Moose/Manual/Roles.pod index b1e45b7..9ad6556 100644 --- a/lib/Moose/Manual/Roles.pod +++ b/lib/Moose/Manual/Roles.pod @@ -196,7 +196,7 @@ If a class composes multiple roles, and those roles have methods of the same name, we will have a conflict. In that case, the composing class is required to provide its I method of the same name. - package Breakdances; + package Breakdancer; use Moose::Role diff --git a/lib/Moose/Manual/Types.pod b/lib/Moose/Manual/Types.pod index 674d26d..7b623d1 100644 --- a/lib/Moose/Manual/Types.pod +++ b/lib/Moose/Manual/Types.pod @@ -59,7 +59,7 @@ In practice, the only difference between C and C is conceptual. C is used as the top-level type in the hierarchy. The rest of these types correspond to existing Perl concepts. For -example, a C is anything that Perl thinks looks like a number. An +example, a C is anything that Perl thinks looks like a number, an C is a blessed reference, etc. The types followed by "[`a]" can be parameterized. So instead of just @@ -124,13 +124,13 @@ instances. =head1 SUBTYPES -Moose uses subtypes in its built-in hierarchy. C is a child of -C for example. +Moose uses subtypes in its built-in hierarchy. For example, C is +a child of C. 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 -valid for the subtype. +constraints defined by the parent(s) will be checked first, followed by +constraints defined by the subtype. 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 specific. @@ -339,7 +339,7 @@ subtype of C that only allows the specified values: enum 'RGB' => qw( red green blue ); -This creates a type named C +This creates a type named C. =head1 ANONYMOUS TYPES diff --git a/lib/Moose/Unsweetened.pod b/lib/Moose/Unsweetened.pod index c5cd0ea..41e0597 100644 --- a/lib/Moose/Unsweetened.pod +++ b/lib/Moose/Unsweetened.pod @@ -220,8 +220,8 @@ email address?"). Also, did you spot the (intentional) bug? It's in the C<_validate_birth_date()> method. We should check that -that value in C<$birth_date> is actually defined and object before we -go and call C on it! Leaving out those checks means our data +the value in C<$birth_date> is actually defined and an object before +we go and call C on it! Leaving out those checks means our data validation code could actually cause our program to die. Oops. Note that if we add a superclass to Person we'll have to change the