s/constraint/coercion/
[gitmo/Moose.git] / grant-description
1 1. Write a set of Moose::Intro::* documentation. This would be a major
2 expansion of the documentation currently in Moose::Intro. These docs
3 will explain concepts in detail, and also explain why and when someone
4 would choose to use a particular feature.
5
6 This differs from the cookbook, which is primarily aimed at showing
7 examples of features in code, and then walking through that code.
8
9 The intro docs would include the following:
10
11     * Moose::Intro::Attributes - what are attributes and how are they
12       used? This piece of documentation would show all the different
13       features available for attributes, including the "initializer",
14       "clearer", "predicate", triggers, etc. It's likely that this
15       will end up being split into two or three separate documents,
16       since Moose has quite a lot of attribute-related features. For
17       example, delegation could easily be in its own document, and it
18       may make sense to split features into a "basic" and "advanced"
19       set.
20
21     * Moose::Intro::Subclassing - subclassing the Moose
22       way. Subclassing in Moose is very simple, but different from the
23       "old school" Perl 5 way.
24
25     * Moose::Intro::MethodModifiers - a detailed discussion of each
26       type of method modifier with explanations of when each is
27       appropriate.
28
29     * Moose::Intro::MooseObject - details of how Moose::Object works
30       and the features it provides for its subclasses. In particular,
31       this documentation would focus on how to use the BUILD,
32       BUILDARGS, and DEMOLISH methods.
33
34     * Moose::Intro::Roles - an explanation of what roles are and
35       discussion of when to use them. This document would discuss how
36       to apply multiple roles to classes, how to apply roles to other
37       roles, and also how to apply roles to an instantiated object.
38
39     * Moose::Intro::Types - an explanation of Moose's type
40       system. This will include information on how and when to create
41       your own types, and how to use coercion.
42
43     * Moose::Intro::Introspection - what are metaclasses,
44       meta-attributes, etc? This document will explain what the
45       metaclasses are, and talk about how they can be used for
46       introspection.
47
48     * Moose::Intro::MooseX - an overview of some useful MooseX
49       modules, specifically MooseX::AttributeHelpers,
50       MooseX::StrictConstructor, MooseX::Params::Validate, and
51       MooseX::Types.
52
53 2. Revise all of the existing cookbook recipes for clarity and
54 simplicity. I've already done this for a few recipes, but there are
55 quite a few left to do.
56
57 3. Write the recipes marked as TODO:
58
59     * Moose::Cookbook::Basics::Recipe8 - Managing complex relations with trigger
60     * Moose::Cookbook::Basics::Recipe11 - BUILD and BUILDARGS
61     * Moose::Cookbook::Roles::Recipe3 - Runtime Role Composition
62     * Moose::Cookbook::Meta::Recipe6 - Hooking into the immutabilization system
63     * Moose::Cookbook::Meta::Recipe7 - Custom meta-instances
64
65 4. Complete API docs for all Moose and Class::MOP classes. Many of
66 these classes have POD which simply lists their methods, without any
67 explanation of what these methods do.