API docs restructuring
a.cheetham at utoronto.ca
Wed Dec 17 17:23:12 UTC 2008
[I originally sent this email to a couple of people working on API
docs, but as soon as I hit the send button I realized that I should
have sent it to the list for broader comment... Sorry if you've
received a duplicate.]
Oh API Document Editors:
We're going to make a change to the way the events are described on
the API pages. Some of the pages have a "Default Listener" in the
table describing the Supported Events.
We want to remove that column entire, and replace it with a column
called "Parameter Description", describing the parameters to the event
listener. You can look at
for an example.
Jonathan, there is one particular Reorderer event that does need
special mention. It's
What's special about it is that if the user/implementor provides a
listener for this event, it will override the default (in other cases,
listeners are simply added to the list).
Another note: If you're looking at existing pages for examples, you
might notice that some of the pages draw tables of events and options
in from a separate page. This is only done in cases where the tables
are shared by multiple pages, so for Uploader and UI Options, that
wouldn't be necessary. For Reorderer, it likely would.
Though for Reorderer, we may want to consider something similar to
what I'm trying with the Inline Edit implementations (dropdown, rich
text). I'm basically referring the reader to the simple text api page,
and documenting which options are being pre-configured. See
What do people think of this way of doing things?
(Note that at time of writing, I've only dumped the defaults object -
I will be adding text to explain the pre-configurations)
Anastasia Cheetham a.cheetham at utoronto.ca
Software Designer, Fluid Project http://fluidproject.org
Adaptive Technology Resource Centre / University of Toronto
More information about the fluid-work