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

Re: Creating API pages

From: David Gash <dgash@google.com>
Date: Thu, 15 Nov 2012 09:05:08 -0800
Message-ID: <CAOm3JBd2nKKD5qLO8pTrwJ-6U3JPKkEnG5MVMMpCpzWtxMCXkg@mail.gmail.com>
To: Scott Rowe <scottrowe@google.com>
Cc: PhistucK <phistuck@gmail.com>, "public-webplatform@w3.org" <public-webplatform@w3.org>, Alex Komoroske <komoroske@google.com>
Scott,
Settled enough for me to move ahead. Barring any major objections, I'll
start on the Web Audio API docs using the revised structure.
Dave

On Thu, Nov 15, 2012 at 8:51 AM, Scott Rowe <scottrowe@google.com> wrote:

> Thanks PhistucK - my thoughts in-line...
> +Scott
>
>
>
> On Wed, Nov 14, 2012 at 11:53 PM, PhistucK <phistuck@gmail.com> wrote:
>
>> See my comments inline.
>>
>> ☆*PhistucK*
>>
>>
>>
>> On Thu, Nov 15, 2012 at 1:12 AM, Scott Rowe <scottrowe@google.com> wrote:
>>
>>> Thanks to everyone who particpated on the call today to discuss the
>>> proposal and the apis architecture. Ahead of meeting notes, I'd like to
>>> review some of the main points and revisit the issues that were not fully
>>> resolved at the end of the call. It's rather imperative that we be able to
>>> move forward with the documenting the APIs, and I think we've resolved
>>> enough of the issues to be able to move forward without having to do too
>>> much revising or reorganizing of our docs down the road.
>>>
>>> Could everyone please take a moment to read this and respond? Thanks!
>>>
>>> *apis architecture*
>>>
>>> We decided to remove the "intermediate" pages (objects, events, methods,
>>> and properties) from the namespace to keep the URLs shorter and eliminate
>>> the need to fill these pages with queries or redirects. The new api
>>> namespace architecture is as follows:
>>>
>>> apis
>>> apis/<apilist>
>>> apis/<apilist>/<apiObject>/<foo-event>
>>> apis/<apilist>/<apiObject>/<bar-method>
>>> apis/<apilist>/<apiObject>/<baz-property>
>>>
>>>
>> Great!
>> Just to be clear. This would be the final URL -
>> apis/webaudio/MediaStreamAudioNode/createMediaStreamSource
>> And not this -
>> apis/webaudio/MediaStreamAudioNode/createMediaStreamSource-method
>>
>> Right?
>>
>
> Right - that's my understanding.
>
>
>
>>
>>
>>
>>> Note: further discussion about the <apilist> namespace identifier is
>>> further on, but assumed here to be maintained.
>>>
>>> I will begin rewriting the proposal for this and reorganizing the webrtc
>>> docs.
>>>
>>> *constants*
>>>
>>> We discussed the possibility of providing for constants (enumerations)
>>> that are shared across several methods within an object. I spoke with our
>>> own Dimitri Glazkov about this. Turns out that an API may provide for the
>>> case where a property could use only part of the enumeration (values 1 and
>>> 2, but not 3) while another property would use all values (1, 2, and 3) of
>>> a given enumeration. Constants are defined for the object, so this scenario
>>> is quite common.
>>>
>>> Now the challenge is how to represent the valid constants for a
>>> particular property. We need a way to specify constants 1 and 2 (but not 3)
>>> for property A, and specify constants 1, 2, and 3 for property B. Probably
>>> the best way is to follow the same approach we take with events, methods,
>>> and properties pages and the "Applies to" field.
>>>
>>> So, each constant would have its own page, i.e.
>>> apis/<apilist>/<apiObject>/<FOO-constant> and the properties page would
>>> have a summary table listing each of the valid constants. The trick here
>>> would be to provide each <FOO-constant> page with multiple "Applies to"
>>> fields so that these could be shared.
>>>
>>> This needs some thought and design expertise. For now, let's just move
>>> forward with constants listed per property.
>>>
>>>
>> Creating a page for every constant seems like a real overkill.
>> I am not sure if this is technically possible, but I propose we add a
>> constant section on every API Object template. Instead of the "Applies
>> to..." approach, we can define a "Possible value" approach. Draw the value
>> from the API Object page.
>>
>> Example -
>> dom/Node has a (special) constants section that is not drawn from
>> anywhere, it is inline. Every constant has a category (node types) a name,
>> a value, a type and a summary.
>> dom/Node/nodeType has a possible values section/field with the following
>> value - dom/Node#ELEMENT_NODE, dom/Node#TEXT_NODE (and so on), or a
>> category of constants - dom/Node#node-type-constants.
>>
>> Creating pages for every constant and adding all of the
>> properties/methods (parameters? sounds complicated. Example -
>> document.evaluate)/objects it applies to sounds like a real pollution.
>>
>
> Yes, I share your concerns. My first thought was, how often does a
> constant need to be reused within a given api object, and how much benefit
> to the user (us) is there in building an infrastructure to support this
> case? In short, is this really necessary? Sure, it would be nice to achieve
> an elegant solution here, but is it a priority? To tell you the truth, I'm
> not convinced.
>
>
>
>>
>>
>>
>>> *exceptions*
>>>
>>> We need to describe the exceptions for a method. Same re-use scenario as
>>> with constants. So apis/<apilist>/<apiObject>/<Bar-exception> and the
>>> ability to "Applies to" to different methods. Note that often API methods
>>> use DOM exceptions, so this template needs to work for both dom and apis.
>>> Could get kind of hairy with multiple "Applies to" fields.
>>>
>>> Needs some thought and design expertise, too. For now, let's just move
>>> forward with exceptions listed per method.
>>>
>>
>> Note that properties can raise exceptions as well when set, I believe.
>>
>> While I agree that common exceptions should have their own pages, I
>> propose a model similar to what I proposed for constants, for exceptions.
>> Instead of adding all of the methods to an "Applies to..." field, fetch
>> the exception from the method page and not the other way around.
>> And in the case of rarely used exceptions (or maybe only exceptions that
>> are used in a single method), add them inline in a special constant section.
>>
>
> As with constants, I'm not convinced that providing for an elegant UI for
> the reuse of exceptions is a high priority. But I think we should continue
> noodling on the subject - good mental exercise!
>
>
>
>>
>>
>>> *Move all apis under dom*
>>>
>>> It was suggested that all of the api pages could be moved under the dom
>>> namespace.
>>>
>>> Early on we decided to keep the dom namespace separate from the apis
>>> namespace. The "non-dom" apis are more clearly defined on their own, and
>>> fitting them within the dom does not add any value. While it is true that
>>> most of the time an API is accessed within the context of a dom object,
>>> i.e. navigator.getUserMedia() or  window.indexedDB.open(), usually this
>>> context is only necessary to create the initial object, i.e. a
>>> LocalMediaStream object or an IDBOpenDBRequest object. That much is
>>> adequately covered in the documentation and needn't be spelled out in the
>>> URLs. And, as was pointed out in the call, our purpose is not to mimic the
>>> document object model in our URLs, but to provide for location and
>>> navigation. Furthermore, nesting everything under a DOM object page
>>> makes the URL longer.
>>>
>>
>> I am also against this, but not strongly. For the same reason as below.
>> However, an argument in favor is that it is kind of hard to decide
>> whether something should be added to dom/ or to apis/.
>>
>
> Yeah, dude, I'm with you! We have to draw the line somewhere though.
>
>
>
>>
>>
>>>
>>> *API Listing pages*
>>>
>>> It was suggested that we remove the API Listing pages from the apis
>>> namespace. I strongly urge us not to do so.
>>>
>>> The API listing pages describe the API by its common names - the names
>>> by which users search for information about the API. It provides
>>> for find-ability where an API has multiple "listing names" - as is the case
>>> with the WebRTC API which is further sub-divided into the MediaStream,
>>> PeerConnection, and DataChannel APIs. These need to be included as
>>> sub-headings in the listing page to fully describe the API.
>>>
>>> The API listing pages provide an overview of how to use the API objects
>>> included in the specification. The best place to do this is within the apis
>>> namespace, rather than a "concepts" or "guides" or other namespace.
>>>
>>> The API listing pages provide for disambiguation between like-named API
>>> objects. Consider two objects:
>>>
>>>    - The MediaStreamAudioSourceNode object from the Web Audio API
>>>    - The MediaStream object from the WebRTC API
>>>
>>> In fact, both of these are the same thing, as creating a
>>> MediaStreamAudioSourceNode is simply passing to that object an object of
>>> type MediaStream:
>>>
>>> MediaStreamAudioSourceNode createMediaStreamSource ( MediaStream
>>> mediaStream );
>>>
>>> If our URLs read, apis/MediaStreamAudioSourceNode and /apis/MediaStream
>>> without any context to differentiate them, users are likely to get confused.
>>>
>>>
>> Listings are very useful wherever they are. I am also against removing
>> listing pages. The more, the merrier.
>>
>
> Well of course I agree. The close approximation - that is, within the apis
> namespace, as in apis/<apilisting> - provides a level of meta data,
> certainly within the current URL-as-navigation methodology, but also long
> term where eventually we collate all of the page meta data into a taxonomy
> and use it to serve up search results.
>
>
>
>>
>>
>>> *Action Item: Proving out the apis architecture*
>>>
>>> I'm concerned that there may have been a miscommunication about the
>>> action item captured at the end of the meeting. This happened while the
>>> meeting was adjourning, and may have been misconstrued. Here's the snippet
>>> from the IRC channel:
>>>
>>> 9:57 AM <sierra_> TASK: someone sanity-check how actual APIs would work
>>> 9:59 AM <sierra_> in apis/<apilist>/objects/<apiObject>/properties , go
>>> to apis/APIobject/properties
>>> 10:00 AM <sierra_> sorry, apis/APIobject
>>>
>>> What I heard was that the action item is to review the apis namespace to
>>> see if there would be collisions between api objects without the
>>> intervening <apilist> object. First, it is unlikely that within our very
>>> limited apis namespace that this will happen (we currently have some 8 or 9
>>> APIs, not counting DOM APIs); second, we can never fully prove the lack of
>>> collisions because we don't have time to review the entire set of standard
>>> APIs - and we certainly can't vet the ones that haven't been created yet.
>>>
>>> Perhaps someone could fill in here why this exercise is necessary and
>>> what it hopes to prove?
>>>
>>> Would it not be more efficacious to simply proceed with maintaining the
>>> <apilist> namespace identifier - as in apis/<apilist>/<apiObject>/<etc.>?
>>>
>>>
>> apilist is useful for context. However, how many developers actually look
>> at the URL of the documentation? I know I do, but I think most do not.
>> I am against removing the apilist part, but not strongly, because I
>> realize it is not that useful for everyone.
>>
>
> Agreed. The URL structure is ultimately a facility for locating - that is,
> for us when creating articles. It is less important as a navigation
> facility for users *once we get our search house in order*. But presently
> search is so crappy that users can't even use it. While it's embarrassing
> to force the users to divine the structure and find articles through the
> URLs, it's pretty much all we've got right now.
>
>
>
>>
>>
>>> Thanks for helping out here!
>>>
>>> +Scott
>>>
>>>
>>>
>>>
>>> On Tue, Nov 13, 2012 at 12:23 PM, PhistucK <phistuck@gmail.com> wrote:
>>>
>>>> I am planning on adding fields for constants within the API Object
>>>> template/form. It might take a few days, though. I hope to work on it on
>>>> Friday or Saturday.
>>>>
>>>> ☆*PhistucK*
>>>>
>>>>
>>>>
>>>> On Tue, Nov 13, 2012 at 9:06 PM, David Gash <dgash@google.com> wrote:
>>>>
>>>>> Scott,
>>>>> For tomorrow's call, apart from the basic issue of the API content
>>>>> architecture, let's discuss the web audio list before I set off creating
>>>>> ~150 pages. Also, I have a few questions about certain parts of the
>>>>> interface that you (or someone else) may be able to answer, below. The
>>>>> numbers refer to the W3C spec<https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html>,
>>>>> and are linked to the specific sections for easy reference.
>>>>>
>>>>> 4.3<https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html#AudioSourceNode>
>>>>>  AudioSourceNode
>>>>> Listed as an "abstract" interface, has no documented properties or
>>>>> methods.
>>>>>
>>>>> 4.11<https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html#MediaElementAudioSourceNode>
>>>>>  MediaElementAudioSourceNode
>>>>> Created in an Audiocontext, has no documented properties or methods.
>>>>>
>>>>> 4.14.1<https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html#PannerNode-sub>PannerNode Constants
>>>>> There's no API structure/path for constants.
>>>>>
>>>>> 4.18<https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html#ChannelSplitterNode>ChannelSplitterNode and
>>>>> 4.19<https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html#ChannelMergerNode>ChannelMergerNode
>>>>> Also have no documented properties or methods.
>>>>>
>>>>> 4.24<https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html#WaveTable>WaveTable and
>>>>> 4.25<https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html#MediaStreamAudioSourceNode>
>>>>>  MediaStreamAudioSourceNode
>>>>> Also have no documented properties or methods.
>>>>>
>>>>> I'm not sure whether to create pages for the objects with no
>>>>> properties or methods, and whether to document the PannerNode constants as
>>>>> properties or... something else. Any input appreciated.
>>>>>
>>>>> Dave
>>>>>
>>>>>
>>>>>
>>>>> On Mon, Nov 12, 2012 at 12:06 PM, Scott Rowe <scottrowe@google.com>wrote:
>>>>>
>>>>>> Thanks Dave! Be sure to share any issues you encounter on this thread.
>>>>>> +Scott
>>>>>>
>>>>>>
>>>>>>
>>>>>> On Mon, Nov 12, 2012 at 11:16 AM, David Gash <dgash@google.com>wrote:
>>>>>>
>>>>>>> Scott / all,
>>>>>>>
>>>>>>> I'm starting to document the web audio API. Based on Scott's
>>>>>>> proposal doc and the W3C specs, the first few topics' URLs will be
>>>>>>> structured thus:
>>>>>>>
>>>>>>> apis/webaudio
>>>>>>>
>>>>>>> apis/webaudio/objects/AudioContext/properties/destination
>>>>>>> apis/webaudio/objects/AudioContext/properties/sampleRate
>>>>>>> apis/webaudio/objects/AudioContext/properties/currentTime
>>>>>>> apis/webaudio/objects/AudioContext/properties/listener
>>>>>>> apis/webaudio/objects/AudioContext/properties/activeSourceCount
>>>>>>> apis/webaudio/objects/AudioContext/methods/createBuffer
>>>>>>> apis/webaudio/objects/AudioContext/methods/decodeAudioData
>>>>>>> apis/webaudio/objects/AudioContext/methods/createBufferSource
>>>>>>> apis/webaudio/objects/AudioContext/methods/. . . etc.
>>>>>>>
>>>>>>> apis/webaudio/objects/AudioNode/properties/context
>>>>>>> apis/webaudio/objects/AudioNode/properties/numberOfInputs
>>>>>>> apis/webaudio/objects/AudioNode/properties/numberOfOutputs
>>>>>>> apis/webaudio/objects/AudioNode/methods/connect
>>>>>>> apis/webaudio/objects/AudioNode/methods/disconnect
>>>>>>>
>>>>>>> apis/webaudio/objects/. . . etc.
>>>>>>>
>>>>>>> There are a lot more objects, properties, and methods in this API,
>>>>>>> of course, but Scott has reviewed this plan and, barring any objections,
>>>>>>> that's the path structure I'll be following.
>>>>>>>
>>>>>>> I plan to outline the entire set before creating any pages, then
>>>>>>> create all the stubs, then go back and fill in.
>>>>>>>
>>>>>>> Cheers,
>>>>>>> Dave
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> On Thu, Nov 8, 2012 at 12: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, 15 November 2012 17:05:37 UTC

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