Re: Creating API pages

Constants usually define the possible values of an object property. See
apis/webrtc/objects/MediaStreamTrack/properties/readyState<http://docs.webplatform.org/wiki/apis/webrtc/objects/MediaStreamTrack/properties/readyState>
for
an example of how I've treated them. In this case, these constants define
the values for the panningModel and distanceModel properties (er,
attributes in w3-speak). This is a good one for the methodology; consider
it caught. Thanks!


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