W3C home > Mailing lists > Public > public-webplatform@w3.org > November 2012

Re: Creating API pages

From: PhistucK <phistuck@gmail.com>
Date: Thu, 8 Nov 2012 23:11:09 +0200
Message-ID: <CABc02_KWgHX140k-w3tFN+Ktdj-OHg0q+EPyiC3OweQqCwzn=w@mail.gmail.com>
To: Scott Rowe <scottrowe@google.com>
Cc: "public-webplatform@w3.org" <public-webplatform@w3.org>
Thank you!

Here is my initial comment.

"Instead, these should be assigned to their respective API objects, as in
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 -
(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).


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
Received on Thursday, 8 November 2012 21:12:17 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 21:20:44 UTC