Re: Creating API pages

Hi Dave,

For the moment, these questions seem to be related to documenting the Web
Audio API specifically, as opposed to documenting APIs generally under the
methodology proposed in this thread. Let's take this up off-line. If we
come up with anything that bears on the creation of API pages, we'll report
it back to the thread.

+Scott



On Tue, Nov 13, 2012 at 11:06 AM, 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
>>>>
>>>>
>>>
>>
>