From: Marcel Grünauer Date: Wed, 4 Feb 2009 00:28:14 +0000 (+0000) Subject: uc/lc consistency, typo and style fixes for Moose::Manual documents X-Git-Tag: 0.67~1 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=d67ce58f8d57e240ded1f1ebdf262456ce2ff5be;p=gitmo%2FMoose.git uc/lc consistency, typo and style fixes for Moose::Manual documents --- diff --git a/lib/Moose/Manual/Attributes.pod b/lib/Moose/Manual/Attributes.pod index cc43ed2..011b01f 100644 --- a/lib/Moose/Manual/Attributes.pod +++ b/lib/Moose/Manual/Attributes.pod @@ -36,7 +36,7 @@ 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 @@ -47,7 +47,7 @@ need to set C, which can be either C (read-write) or C that has no accessors, which is pointless unless you're doing some deep, dark magic). -=head2 Accessor Methods +=head2 Accessor methods Each attribute has one or more accessor methods. An accessor lets you read and write the value of that attribute for an object. @@ -94,7 +94,7 @@ tedious, you're right! Fortunately, Moose provides a powerful extension system that lets override the default naming conventions. See L for more details. -=head2 Predicate and Clearer Methods +=head2 Predicate and clearer methods Moose allows you to explicitly distinguish between a false or undefined attribute value and an attribute which has not been set. If @@ -145,7 +145,7 @@ predicate, and clearer method. By default, Moose does not make a predicate or clearer for you. You must explicitly provide names for them. -=head2 Required or Not? +=head2 Required or not? By default, all attributes are optional, and do not need to be provided at object construction time. If you want to make an attribute @@ -172,7 +172,7 @@ clearer doesn't make much sense. In some cases, it might be handy to have a I C and C for a required attribute. -=head2 Default and Builder Methods +=head2 Default and builder methods Attributes can have default values, and Moose provides two ways to specify that default. @@ -256,7 +256,7 @@ subclasses. We strongly recommend that you use a C instead of a C for anything beyond the most trivial default. -=head2 Laziness and lazy_build +=head2 Laziness and C Moose lets you defer attribute population by making an attribute C: @@ -337,7 +337,7 @@ always provide your own: Options that you explicitly provide are always used in favor of Moose's internal defaults. -=head2 Constructor Parameters (init_arg) +=head2 Constructor parameters (C) By default, each attribute can be passed by name to the class's constructor. On occasion, you may want to use a different name for @@ -366,7 +366,7 @@ the constructor. This is particularly handy for private attributes: By setting the C to C, we make it impossible to set this attribute when creating a new object. -=head2 Weak References +=head2 Weak references Moose has built-in support for weak references. If you set the C option to a true value, then it will call @@ -407,7 +407,7 @@ trigger is only called when the attribute is set, as opposed to whenever the accessor is called. Second, it is also called if the attribute is set via a lazy default or builder. -=head2 Attribute Types +=head2 Attribute types Attributes can be restricted to only accept certain types: @@ -563,7 +563,7 @@ You can provide a piece of documentation as a string for an attribute: Moose does absolutely nothing with this information other than store it. -=head2 The C Option +=head2 The C option If your attribute is an array reference or hash reference, the C option will make Moose dereference the value when it is diff --git a/lib/Moose/Manual/BestPractices.pod b/lib/Moose/Manual/BestPractices.pod index 1814b1a..8204dac 100644 --- a/lib/Moose/Manual/BestPractices.pod +++ b/lib/Moose/Manual/BestPractices.pod @@ -13,7 +13,7 @@ and using them consistently makes everyone's life easier. Of course, as with any list of "best practices", these are really just opinions. Feel free to ignore us. -=head2 "No Moose" and Immutabilize +=head2 C and immutabilize We recommend that you end your Moose class definitions by removing the Moose sugar and making your class immutable. @@ -35,7 +35,7 @@ Moose sugar and making your class immutable. 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 +=head2 Always call C If you override the C method in your class, make sure to play nice and call C to handle cases you're not @@ -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 C Feature +=head2 Don't use the C feature Don't know what we're talking about? That's fine. -=head2 Use C Instead of C 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. @@ -66,7 +66,7 @@ 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 and 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 @@ -85,13 +85,13 @@ If you I make an attribute read-write, consider making the writer a separate private method. Narrower APIs are easy to maintain, and mutable state is trouble. -=head2 Think Twice Before Changing an Attribute's Type in a Subclass +=head2 Think twice before changing an attribute's type in a subclass 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 L Instead of C +=head2 Use L instead of C The C feature is a bit troublesome. Directly exposing a complex attribute is ugly. Instead, consider using @@ -99,18 +99,18 @@ L to define an API that exposes those pieces of functionality that need exposing. Then you can expose just the functionality that you want. -=head2 Namespace Your Types +=head2 Namespace your types Use some sort of namespacing convention for type names. We recommend something like "MyApp.Type.Foo". I use "::" as the namespace separator, since that overlaps with actual class names. -=head2 Coercion Instead of Unions +=head2 Coercion instead of unions Consider using a type coercion instead of a type union. This was covered at length in L. -=head2 Define All Your Types in One Module +=head2 Define all your types in one module Define all your types and coercions in one module. This was also covered in L. diff --git a/lib/Moose/Manual/Concepts.pod b/lib/Moose/Manual/Concepts.pod index 0b943b5..9820b05 100644 --- a/lib/Moose/Manual/Concepts.pod +++ b/lib/Moose/Manual/Concepts.pod @@ -2,7 +2,7 @@ =head1 NAME -Moose::Manual::Concepts - Moose OO Concepts +Moose::Manual::Concepts - Moose OO concepts =head1 MOOSE CONCEPTS (VS "OLD SCHOOL" Perl) @@ -148,7 +148,7 @@ Role are somewhat like mixins or interfaces in other OO languages. $self->is_broken(1); }; -=head2 Method Modifiers +=head2 Method modifiers A B is a hook that is called when a named method is called. For example, you could say "before calling C, call @@ -212,7 +212,7 @@ need to, but you usually don't. With old school Perl 5, this is the C method, but with Moose it is the C method. -=head2 Object Instance +=head2 Object instance An object instance is a specific noun in the class's "category". For example, one specific Person or User. An instance is created by the @@ -225,7 +225,7 @@ In old school Perl 5, this is often a blessed hash reference. With Moose, you should never need to know what your object instance actually is. (ok, it's usually a blessed hashref with Moose too) -=head2 Moose VS Old School Summary +=head2 Moose vs old school summary =over 4 diff --git a/lib/Moose/Manual/Construction.pod b/lib/Moose/Manual/Construction.pod index 1a17e64..9f35a9d 100644 --- a/lib/Moose/Manual/Construction.pod +++ b/lib/Moose/Manual/Construction.pod @@ -91,7 +91,7 @@ object creation. debug( 'Made a new person - SSN = ', $self->ssn, ); } -=head3 BUILD and Parent Classes +=head3 BUILD and parent classes The interaction between multiple C methods in an inheritance hierarchy is different from normal Perl methods. B If you only look at one extension, it should be this one. It provides the equivalent of delegation for all of Perl's native data types, such @@ -49,7 +49,7 @@ This lets you create I cleaner and fluent APIs. Instead of directly exposing an array reference, we have three well-named, easy to use methods. -=head1 MooseX::StrictConstructor +=head1 L By default, Moose lets you pass any old junk into a class's constructor. If you load L, your class will @@ -69,7 +69,7 @@ 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 +=head1 L We have high hopes for the future of L and L. However, for now we recommend the decidedly more @@ -90,7 +90,7 @@ arguments. ... } -=head1 MooseX::Getopt +=head1 L This is a role which adds a C method to your class. This is a constructor that takes the command line options and @@ -128,7 +128,7 @@ From the command line, someone can execute the script: foo@example> foo --input /path/to/input --output /path/to/output -=head1 MooseX::Singleton +=head1 L To be honest, using a singleton is often a hack, but it sure is a handy hack. L lets you have a Moose class that's a @@ -148,7 +148,7 @@ There are literally dozens of other extensions on CPAN. This is a list of extensions that you might find useful, but we're not quite ready to endorse just yet. -=head2 MooseX::Declare +=head2 L Extends Perl with Moose-based keywords using C. Very cool, but still new and experimental. @@ -161,7 +161,7 @@ cool, but still new and experimental. method login (Str $password) { ... } } -=head2 MooseX::Types +=head2 L This extension helps you build a type library for your application. It also lets you pre-declare type names and use them as barewords. @@ -178,7 +178,7 @@ One nice feature is that those bareword names are actually namespaced in Moose's type registry, so multiple applications can use the same bareword names, even if the type definitions differ. -=head2 MooseX::Types::Structured +=head2 L This extension builds on top of L to let you declare complex data structure types. @@ -196,7 +196,7 @@ complex data structure types. Of course, you could always use objects to represent these sorts of things too. -=head2 MooseX::ClassAttribute +=head2 L This extension provides class attributes for Moose classes. The declared class attributes are introspectable just like regular Moose @@ -211,31 +211,31 @@ attributes. class_has 'Cache' => ( ... ); -=head2 MooseX::Daemonize +=head2 L This is a role that provides a number of methods useful for creating a daemon, including methods for starting and stopping, managing a PID file, and signal handling. -=head2 MooseX::Role::Parameterized +=head2 L If you find yourself wanting a role that customizes itself for each consumer, this is the tool for you. With this module, you can create a role that accepts parameters and generates attributes, methods, etc on a customized basis for each consumer. -=head2 MooseX::POE +=head2 L This is a small wrapper that ties together a Moose class with C, and gives you an C sugar function to declare event handlers. -=head2 MooseX::FollowPBP +=head2 L Automatically names all accessors I-style, "get_size" and "set_size". -=head2 MooseX::SemiAffordanceAccessor +=head2 L Automatically names all accessors with an explicit set and implicit get, "size" and "set_size". diff --git a/lib/Moose/Manual/Roles.pod b/lib/Moose/Manual/Roles.pod index 00eb954..73b08df 100644 --- a/lib/Moose/Manual/Roles.pod +++ b/lib/Moose/Manual/Roles.pod @@ -2,7 +2,7 @@ =head1 NAME -Moose::Manual::Roles - Roles, an Alternative to Deep Hierarchies and Base Classes +Moose::Manual::Roles - Roles, an alternative to deep hierarchies and base classes =head1 WHAT IS A ROLE? diff --git a/lib/Moose/Manual/Types.pod b/lib/Moose/Manual/Types.pod index e9489ed..d743b3d 100644 --- a/lib/Moose/Manual/Types.pod +++ b/lib/Moose/Manual/Types.pod @@ -2,7 +2,7 @@ =head1 NAME -Moose::Manual::Types - Moose's Type System +Moose::Manual::Types - Moose's type system =head1 TYPES IN PERL? @@ -150,7 +150,7 @@ Here's a simple (and useful) subtype example: Note that the sugar functions for working with types are all exported by L. -=head2 Creating a New Type (That Isn't a Subtype) +=head2 Creating a new type (that isn't a subtype) You can also create new top-level types: @@ -222,7 +222,7 @@ C attribute parameter to a true value: This code example will do the right thing, and the newly created object will have C<[ 42 ]> as its C attribute. -=head2 Deep Coercion +=head2 Deep coercion Deep coercion is the coercion of type parameters for parameterized types. Let's take these types as an example: