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

Re: Creating API pages

From: David Gash <dgash@google.com>
Date: Tue, 13 Nov 2012 11:06:04 -0800
Message-ID: <CAOm3JBf-0rfpi4TApxxVyE=6YsNpYPLERvKn4Wc-LzTDFn25Hw@mail.gmail.com>
To: Scott Rowe <scottrowe@google.com>
Cc: "public-webplatform@w3.org" <public-webplatform@w3.org>
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 Tuesday, 13 November 2012 19:06:32 UTC

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