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>
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
and are linked to the specific sections for easy reference.

Listed as an "abstract" interface, has no documented properties or methods.

Created in an Audiocontext, has no documented properties or methods.

There's no API structure/path for constants.

Also have no documented properties or methods.

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.


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 : Tuesday, 6 January 2015 21:20:44 UTC