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 12:31:25 -0800
Message-ID: <CAOm3JBeTUaC+ze6TCxtR9dCvmmjt3AZmGeK69hiars=xUZ8FUw@mail.gmail.com>
To: PhistucK <phistuck@gmail.com>
Cc: Scott Rowe <scottrowe@google.com>, "public-webplatform@w3.org" <public-webplatform@w3.org>
Excellent, thanks.
dave

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 Tuesday, 13 November 2012 20:31:53 UTC

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