Moose Documentation TODO list (Was: moose book ?)

Benh, great idea :)

On Apr 7, 2008, at 9:16 PM, benh wrote:
> Do you have a list of pages/POD that need to be updated and worked
> out? or just a wish list even? I would be willing to grab a page or
> two and help out.

Yes, actually I do have a TODO list, it has mostly been in my head  
though, but I can transcribe it. Anyone who wants to grab an item is  
more then welcome. Perhaps we should even put this in the repo  
somewhere too.

Here are the more specific items:

- add docs for BUILD and DEMOLISH to Moose::Object
- copy docs for Class::MOP::Attribute options (reader, writer,  
accessor, predicate, etc) up to docs in Moose.pm
- add the item about DEMOLISH eating the value of $@ (see recent  
emails with Ernesto) to Moose::Cookbook::WTF
- check over Moose::Cookbook::WTF and Moose::Cookbook::FAQ to make  
sure those are still in sync

Here are some more general items:

- overall improvement of linkages between Class::MOP::* and  
Moose::Meta::*
- specifically docs for before, around & after linked to  
Class::MOP::Class methods
- improve the docs on immutable

I roughed out some ideas for additional cookbook recipes as well,  
here is a list of them (same list is in Moose::Cookbook).  
Additionally if you have other recipe ideas you are more them welcome  
to venture off alone. The basic pattern of the cookbook is to pick  
one (or a few) features to show off and to keep the example code as  
straightforward as possible (to the point of being contrived if need  
be).

- recipe 6 (augment/inner) needs writing
- recipe 7 (immutable) needs an example and writing
- recipe 8 (trigger) we have a test to base the example on (see  
Moose::Cookbook POD for that), just needs some polishing .. and then  
recipe needs to be written
- recipe 11 (advanced role composition) needs an example and writing
- recipe 12 (runtime role composition) needs an example and writing
- recipe 20 (intro to "meta") needs an example and writing
- recipe 22 (meta attribute traits) needs an example and writing
- recipe 23 (meta instance) needs an example and writing  
(MX::InsideOut might be a good example)
- recipe 24 (meta class) needs an example and writing

And then we also have the Moose::Cookbook::Snacks, which castaway  
started. They are smaller then recipes, and so much more focused. The  
idea is to be able to go into greater detail on a subject which is  
not big or interesting enough to deserve it's own recipe, but is not  
easily documented elsewhere. Couple ideas for this might be:

- using BUILD instead of overriding new
- adding messages to your types
- using parameterized collection types ArrayRef, HashRef
- the Maybe[`a] type
- using builder vs. using default
- using custom attribute metaclasses
- using custom attribute traits
- type coercions with parameterized types
- type coercions with type unions

Okay, thats about all I got in my head for now. Anything else people  
want to add to this, feel free.

Thanks,

- Stevan