Re: Creating API pages

Thank you!

Here is my initial comment.

"Instead, these should be assigned to their respective API objects, as in
apis/indexeddb/objects/indexedDB/methods/open."
While this is a step in the right direction (much better than
apis/indexeddb/methods/open), I do not think this is the correct and most
accurate way to describe it.
I strongly prefer correctness and accuracy here (and wherever), so I would
like to propose that this should be the right path -
apis/indexeddb/objects/IDBFactory/methods/open
(I have gone over the Working Draft specification document and that seems
to be the interface to which window.indexedDB.open belongs, correct me if I
am wrong.)
Then, I guess dom/window (which should actually be dom/Window, in my
opinion, or something like that) would have dom/properties/indexedDB, which
would have a type of IDBFactory and automatically draw and show all of its
members (this needs to be developed, of course).

To summarize, I think we must define methods, events and properties that
apply to interfaces only. Make properties have full blown types and draw
information from the interfaces.
Full inheritance support is also a must (and needs to be developed as
well). I am trying to clean up the MSDN "Members" section from the dom/x
pages and it keeps listing stuff like "constructor" as a property, which is
supposed to come from Object. Adding "Object" (wherever it is...) as a
subclass to everything feels pretty stupid.
My first hunch was to simply ignore it and remove it, but I do not think
this is the right thing to do. Even though it is practically everywhere, it
should still be listed (since it does apply).

☆*PhistucK*



On Thu, Nov 8, 2012 at 10:03 PM, Scott Rowe <scottrowe@google.com> wrote:

> When I sat down to document the process for creating API pages, using the
> WebRTC documentation as the poster child, I found more questions than
> answers. I realized that we did not have a good story here, so I did my
> best to fill in the holes with a methodology that attempts to solve the
> problems I found.
>
> You find this methodology described in WPD:Creating_API_pages<http://docs.webplatform.org/wiki/WPD:Creating_API_pages>
> .
>
> Note that it started out as a how-to for contributors, but quickly became
> a proposal. So parts of it will read either way. Don't be alarmed. The
> purpose of the document is to provide you with a methodology to try on as
> you do what I did - test it out with your own API pages.
>
> As you do, please don't update the methodology in that page - let's
> discuss it first. We can use this thread for the discussion.
>
> Thanks for your help!
>
> +Scott
>
>