Re: Creating API pages

At least in Chrome (I did not try any other browser), it seems like
indexedDB provides all of the methods of the IDBFactory interface.
indexedDB.deleteDatabase
function deleteDatabase() { [native code] }
indexedDB.cmp
function cmp() { [native code] }
indexedDB.open
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?
☆*PhistucK*



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