Re: Creating API pages

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
>>
>>
>