Re: Creating API pages

Replies inlined "SIERRA":

On Thu, Nov 15, 2012 at 12:12 PM, Scott Rowe <scottrowe@google.com> wrote:
> Thanks Mike!
> I'd like to add some clarification, if I may...
>
>
> On Thu, Nov 15, 2012 at 7:59 AM, Mike Sierra
> <letmespellitoutforyou@gmail.com> wrote:
>>
>> 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)
>
>
> Is this change in terminology necessary? We were working from this:
>
> apis/<apilist>/<apiObject>/<event|method|property>

SIERRA: Provisional change in terminology b/c I misunderstood
somewhere along the way what <apilist> meant.  Came into the thread
midstream, so sorry if I missed the details.



>> * The "apis" page would list available APIs by the spec-level
>>   conceptual handler by which they're commonly referred.
>
>
> Yes, under the terminology in the proposal, the apis page is just a category
> page that lists all of the sub pages.
>
>
>>
>>
>> * Each "apiName" page lists available apiInterfaces. This page would
>>   discuss how to use the API as a whole.
>
>
> Yes, the <apilist> page describes the API by its common name, i.e.
> apis/webrtc
>
>>
>>
>> * Each "apiInterface" would feature tables listing out...
>
>
> Yes, the <apiObject> page provides an overview of the object and lists its
> events, methods, and properties.
>
>>
>>
>> * ...properties, methods, and events.
>
>
> Yes, these types describe the individual members of the API object.
>
>>
>>
>> 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.
>
>
> A certain amount of infrastructure needs to be built to support this. For
> now we can just include the constants and exceptions within the properties
> and methods to which they apply.
>
>
>>
>>
>> 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?
>
>
> The <apilist> namespace identifier is written in all lower case because it
> is only a namespace identifier. The <apiObject> is written in camel case
> because it is the proper name of the object. For example,
> apis/indexeddb/IndexedDB or apis/webrtc/MediaStream.
>
>
>>
>>
>> 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.
>
>
> This is already in place. See apis/webrtc/objects/LocalMediaStream.

SIERRA: Awesome. Missed that. Still learning the system.


>> * Where appropriate, note the DOM node used to access each interface
>>   object: document, navigator, window, video, audio, etc.
>
>
> Worth a try! If we can come up with something slicker than just a link in
> the description, I'm all for it.
>
>>
>>
>> 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.
>
>
> I'm not sure what you mean here.

SIERRA: Maybe I misunderstood the thread, but what I have in mind is
ubiquitous DOM APIs such as classlist & dataset. Would these be under
dom/ or apis/ ?

>>
>> --Mike Sierra
>
>
> Thanks Mike!
> +Scott
>

SIERRA: Thx, out.



>> 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:43:43 UTC