develooper Front page | perl.moose | Postings from March 2009

CMOP docs, API changes, deprecations, etc

From:
Dave Rolsky
Date:
March 17, 2009 11:10
Subject:
CMOP docs, API changes, deprecations, etc
Message ID:
alpine.DEB.0.9999.0903171254530.11236@urth.org
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)
============================================================*/



nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About