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

Re: Creating API pages

From: David Gash <dgash@google.com>
Date: Mon, 12 Nov 2012 11:16:26 -0800
Message-ID: <CAOm3JBfqS-SmhfOCniGx9-4wnsNPU7ANv6SUe6tcO+SycaKnrA@mail.gmail.com>
To: Scott Rowe <scottrowe@google.com>
Cc: "public-webplatform@w3.org" <public-webplatform@w3.org>
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 14:32:32 UTC

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