So I've finished revamping all of the Class::MOP API documentation.
The new docs have a specific reader in mind. That reader is someone who is
using CMOP to introspect existing classes, and _maybe_ tweaking classes
uses APIs look ->add_method, ->add_attribute, etc.
Most of these readers will arrive at CMOP by way of Moose, and are
probably already using Moose in their own code.
That means the focus is on presenting the introspection and modification
APIs, without a lot of theory. I've also tried to organize the methods so
that the ones they are most likely to want come first in the docs.
The docs are they were before didn't seem to have a clear idea of who the
reader was. However, they did seem to think that the reader might be
implementing something on top of CMOP like Moose itself. I think history
has shown that to be somewhat unlikely.
Instead, people who might have done that have instead written extensions
to Moose. Those people are best served by good docs on writing Moose
extensions in the Moose distro, and I think those docs have been improved
over the past year or so.
Towards my goal of serving this notional reader, you'll notice that there
are a whole bunch of methods that have intentionally not been documented.
By and large, these methods are ones that I think should be renamed to
start with a leading underscore, because they are really only useful if
you're writing a subclass (or role) for the given module.
They also are methods that I just couldn't imagine documenting, because
my notional reader would not find them useful. Often there is another
similar method that the reader can use. Other times, they really should
never be calling these methods directly.
But since there is some debate over how to change the names, how/when/if
to do these deprecations, I've made a couple branches.
One is called "renames-and-deprecations".
This branch should be rebased at the HEAD of master, and consists of a set
of changes to make various methods protected. Mostly this consisted of
adding a leading underscore to the name. The existing method name still
exists, and warns that it has been made private when called.
I also added deprecation warnings for a few methods that have been marked
deprecated in the docs for a long time (and just removed them from the
docs entirely).
Finally, for CMOP::Module->create, I renamed it to ->_instantiate_module
and changed the API quite a bit.
There is another branch called "refactor-immutable". Trying to document
the immutable code was annoying me, cause it was much more complicated
than it needed to be. I refactored it quite a bit to simplify its handling
of state in this branch.
The changes means that there is one CMOP::Immutable object per metaclass.
The metaclass creates it once when $metaclass->make_immutable is called.
After that, future calls to ->make_(im)?mutable re-use this object.
I also changed the internals of CMOP::Immutable quite a bit to simplify
them. The make_X methods no longer accept a list of options. Instead, the
options passed to the constructor are always used (this is effectively how
things worked before, but in a much more convoluted way).
I'd appreciate review of these two branches. I imagine the latter will be
much less controversial, since I don't think anyone loved the immutable
API.
-dave
/*============================================================
http://VegGuide.org http://blog.urth.org
Your guide to all that's veg House Absolute(ly Pointless)
============================================================*/
