Re: Creating API pages

Re "Action Item", Along with Julee, I plan to assemble a list of URLs
based on interface declarations in a generous sample of W3C specs,
with comments noting any items I run across that don't fit into the
structure discussed in the meeting.  It appears throughout the
meeting, I was unclear about the purpose of <apilist>, which was
reflected in my notes for the action item. Let me clarify
terminology:

/apis/apiName/apiInterface/(property|method|event)

* The "apis" page would list available APIs by the spec-level
  conceptual handler by which they're commonly referred.

* Each "apiName" page lists available apiInterfaces. This page would
  discuss how to use the API as a whole.

* Each "apiInterface" would feature tables listing out...

* ...properties, methods, and events.

NOTE: open question whether to represent constants and exceptions on
separate pages?  I tend to think they belong in tables on the
apiInterface page, partly because they're conceptually tied to the
interface as a whole & partly b/c I expect them to brief & easy to
scan at that level.

Not sure if I missed this point earlier, but there are many cases
where the "apiName" would match one of the component "apiInterface"
items.  Examples: File API defines File, FileList, FileReader, and
Blob interfaces; Geolocation API defines Geolocation, Position,
PositionOptions, PositionError, and Coordinates interfaces. I think
users would understand the distinction, but I want to make sure we're
aware of the issue. Was this the major concern about collisions?

I'd suggest a couple of template enhancements:

* Specify when one API interface extends another.  E.g., I set up a
  page for CSSRegionStyleRule that inherits from CSSRule. Ideal if
  one interface can slurp in the other's.

* Where appropriate, note the DOM node used to access each interface
  object: document, navigator, window, video, audio, etc.

On this last point, perhaps remaining elements within dom/apis could
then link back? I understand this will be the place for the remaining set
of core DOM APIs.

--Mike Sierra



On Wed, Nov 14, 2012 at 6:12 PM, Scott Rowe <scottrowe@google.com> wrote:
> Thanks to everyone who particpated on the call today to discuss the proposal
> and the apis architecture. Ahead of meeting notes, I'd like to review some
> of the main points and revisit the issues that were not fully resolved at
> the end of the call. It's rather imperative that we be able to move forward
> with the documenting the APIs, and I think we've resolved enough of the
> issues to be able to move forward without having to do too much revising or
> reorganizing of our docs down the road.
>
> Could everyone please take a moment to read this and respond? Thanks!
>
> apis architecture
>
> We decided to remove the "intermediate" pages (objects, events, methods, and
> properties) from the namespace to keep the URLs shorter and eliminate the
> need to fill these pages with queries or redirects. The new api namespace
> architecture is as follows:
>
> apis
> apis/<apilist>
> apis/<apilist>/<apiObject>/<foo-event>
> apis/<apilist>/<apiObject>/<bar-method>
> apis/<apilist>/<apiObject>/<baz-property>
>
> Note: further discussion about the <apilist> namespace identifier is further
> on, but assumed here to be maintained.
>
> I will begin rewriting the proposal for this and reorganizing the webrtc
> docs.
>
> constants
>
> We discussed the possibility of providing for constants (enumerations) that
> are shared across several methods within an object. I spoke with our own
> Dimitri Glazkov about this. Turns out that an API may provide for the case
> where a property could use only part of the enumeration (values 1 and 2, but
> not 3) while another property would use all values (1, 2, and 3) of a given
> enumeration. Constants are defined for the object, so this scenario is quite
> common.
>
> Now the challenge is how to represent the valid constants for a particular
> property. We need a way to specify constants 1 and 2 (but not 3) for
> property A, and specify constants 1, 2, and 3 for property B. Probably the
> best way is to follow the same approach we take with events, methods, and
> properties pages and the "Applies to" field.
>
> So, each constant would have its own page, i.e.
> apis/<apilist>/<apiObject>/<FOO-constant> and the properties page would have
> a summary table listing each of the valid constants. The trick here would be
> to provide each <FOO-constant> page with multiple "Applies to" fields so
> that these could be shared.
>
> This needs some thought and design expertise. For now, let's just move
> forward with constants listed per property.
>
> exceptions
>
> We need to describe the exceptions for a method. Same re-use scenario as
> with constants. So apis/<apilist>/<apiObject>/<Bar-exception> and the
> ability to "Applies to" to different methods. Note that often API methods
> use DOM exceptions, so this template needs to work for both dom and apis.
> Could get kind of hairy with multiple "Applies to" fields.
>
> Needs some thought and design expertise, too. For now, let's just move
> forward with exceptions listed per method.
>
> Move all apis under dom
>
> It was suggested that all of the api pages could be moved under the dom
> namespace.
>
> Early on we decided to keep the dom namespace separate from the apis
> namespace. The "non-dom" apis are more clearly defined on their own, and
> fitting them within the dom does not add any value. While it is true that
> most of the time an API is accessed within the context of a dom object, i..e.
> navigator.getUserMedia() or  window.indexedDB.open(), usually this context
> is only necessary to create the initial object, i.e. a LocalMediaStream
> object or an IDBOpenDBRequest object. That much is adequately covered in the
> documentation and needn't be spelled out in the URLs. And, as was pointed
> out in the call, our purpose is not to mimic the document object model in
> our URLs, but to provide for location and navigation. Furthermore, nesting
> everything under a DOM object page makes the URL longer.
>
> API Listing pages
>
> It was suggested that we remove the API Listing pages from the apis
> namespace. I strongly urge us not to do so.
>
> The API listing pages describe the API by its common names - the names by
> which users search for information about the API. It provides for
> find-ability where an API has multiple "listing names" - as is the case with
> the WebRTC API which is further sub-divided into the MediaStream,
> PeerConnection, and DataChannel APIs. These need to be included as
> sub-headings in the listing page to fully describe the API.
>
> The API listing pages provide an overview of how to use the API objects
> included in the specification. The best place to do this is within the apis
> namespace, rather than a "concepts" or "guides" or other namespace.
>
> The API listing pages provide for disambiguation between like-named API
> objects. Consider two objects:
>
> The MediaStreamAudioSourceNode object from the Web Audio API
> The MediaStream object from the WebRTC API
>
> In fact, both of these are the same thing, as creating a
> MediaStreamAudioSourceNode is simply passing to that object an object of
> type MediaStream:
>
> MediaStreamAudioSourceNode createMediaStreamSource ( MediaStream mediaStream
> );
>
> If our URLs read, apis/MediaStreamAudioSourceNode and /apis/MediaStream
> without any context to differentiate them, users are likely to get confused.
>
> Action Item: Proving out the apis architecture
>
> I'm concerned that there may have been a miscommunication about the action
> item captured at the end of the meeting. This happened while the meeting was
> adjourning, and may have been misconstrued. Here's the snippet from the IRC
> channel:
>
> 9:57 AM <sierra_> TASK: someone sanity-check how actual APIs would work
> 9:59 AM <sierra_> in apis/<apilist>/objects/<apiObject>/properties , go to
> apis/APIobject/properties
> 10:00 AM <sierra_> sorry, apis/APIobject
>
> What I heard was that the action item is to review the apis namespace to see
> if there would be collisions between api objects without the intervening
> <apilist> object. First, it is unlikely that within our very limited apis
> namespace that this will happen (we currently have some 8 or 9 APIs, not
> counting DOM APIs); second, we can never fully prove the lack of collisions
> because we don't have time to review the entire set of standard APIs - and
> we certainly can't vet the ones that haven't been created yet.
>
> Perhaps someone could fill in here why this exercise is necessary and what
> it hopes to prove?
>
> Would it not be more efficacious to simply proceed with maintaining the
> <apilist> namespace identifier - as in apis/<apilist>/<apiObject>/<etc.>?
>
> Thanks for helping out here!
>
> +Scott
>
>
>
>
> 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, and are linked to the specific sections for
>>> easy reference.
>>>
>>> 4.3 AudioSourceNode
>>> Listed as an "abstract" interface, has no documented properties or
>>> methods.
>>>
>>> 4.11 MediaElementAudioSourceNode
>>> Created in an Audiocontext, has no documented properties or methods.
>>>
>>> 4.14.1 PannerNode Constants
>>> There's no API structure/path for constants.
>>>
>>> 4.18 ChannelSplitterNode and
>>> 4.19 ChannelMergerNode
>>> Also have no documented properties or methods.
>>>
>>> 4.24 WaveTable and
>>> 4.25 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.
>>>>>>
>>>>>> 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 Thursday, 15 November 2012 17:19:32 UTC