API docs restructuring

[Anastasia Cheetham]

[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
  http://wiki.fluidproject.org/display/fluid/Simple+Text+Inline+Edit+API
for an example.

Jonathan, there is one particular Reorderer event that does need  
special mention. It's
    onShowKeyboardDropwarning.setPosition
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
http://wiki.fluidproject.org/display/fluid/Simple+Text+Inline+Edit+API
and
http://wiki.fluidproject.org/display/fluid/Dropdown+Inline+Edit+API
and
http://wiki.fluidproject.org/display/fluid/Rich+Text+Inline+Edit+API
for example.

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