JavaScript APIs organization

Hi,

It looks like the current organization of the documentation for
JavaScript APIs (and in particular their methods and properties) is a
bit of a mess.

Some are documented in sub-pages of
http://docs.webplatform.org/wiki/apis (grouped in somewhat arbitrary
fashion), some are documented under http://docs.webplatform.org/wiki/dom
(see http://docs.webplatform.org/wiki/dom/methods to get an idea).

The organization under http://docs.webplatform.org/wiki/dom is also very
messy, since methods and properties are put directly under
http://docs.webplatform.org/wiki/dom/methods and
http://docs.webplatform.org/wiki/dom/properties, not under a specific
interface, so name clashs are pretty much guaranteed down the line.

I'm not sure what the intent of the "apis/" space is; maybe is it for
documenting APIs at a high level, while leaving specific documentation
to sub pages in dom/... ? That probably ought to be clarified at the
very least.

I also suggest the whole dom/ subtree be re-organized to move properties
and methods to their specific interfaces, e.g. move
dom/properties/attribute (sic) to dom/Element/attributes (I'm not sure
we need to distinguish them in subtree properties / methods, but I would
be fine either way). Otherwise, name clashes are guaranteed.

Also, is it the intent that properties and methods of objects such as
window or navigator be also documented under the dom/ subtree? 

What about Math.*?

Thanks for any input!

Dom

Received on Monday, 15 October 2012 09:07:57 UTC