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:38:54 +0200
Message-ID: <CABc02_++Jp32QYqNRMO3H3n-j20jxy0NcfLRjX8WTBbt0F9RKg@mail.gmail.com>
To: Scott Rowe <scottrowe@google.com>
Cc: Eliot Graff <Eliot.Graff@microsoft.com>, "public-webplatform@w3.org" <public-webplatform@w3.org>
At least in Chrome (I did not try any other browser), it seems like
indexedDB provides all of the methods of the IDBFactory interface.
function deleteDatabase() { [native code] }
function cmp() { [native code] }
function open() { [native code] }
So unless the implementation is incorrect, I do not see any reason
for apis/indexeddb/objects/indexedDB/methods/open.
(I also do not see a reason for apis/indexeddb/objects/indexedDB at all,
since like I mentioned, it should be located at dom/methods/indexedDB or
something like that.)

So does everyone agree that members should only apply to interfaces and
that dom/window (as an example) should actually be of type dom/Window (or
something like that)?
Should I start moving things around to reflect that everywhere?

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

> Hi PhistucK,
> You're absolutely right, apis/indexeddb/objects/IDBFactory/methods/open
> is correct - but so is apis/indexeddb/objects/indexedDB/methods/open. In
> one bit of quirkiness that has yet to be fully explained to me  (Eliot, you
> were in on this, can you lend a word or two?), the IndexedDB API includes
> this weird little indexedDB object that interfaces with IDBFactory but has
> only one method, open(). It's sole purpose seems to be to provide
> developers with a "vanity" indexedDB.open() method. I think good
> documentation should include this.
> But the reason I used that example is because it points out the need to
> distinguish between the "indexeddb" API name and the "indexedDB" object
> name.
> +Scott
> On Thu, Nov 8, 2012 at 1:11 PM, PhistucK <phistuck@gmail.com> wrote:
>> 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
Received on Thursday, 8 November 2012 21:40:02 UTC

This archive was generated by hypermail 2.3.1 : Wednesday, 8 May 2013 19:57:35 UTC