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.