Re: A categorization/placing problem - event/property pages

Hi, folks-

I believe I'm with Scott here. The Open Web Platform is a bit messy, and 
we don't do anyone a favor by trying to hide the important-but-messy 
bits behind a veil.

At the same time, however, I agree (and think Scott would, too) that 
where it makes sense, the 'event' ref page should contain the listings 
and description for the equivalent object property (onfoo) and attribute 
(onfoo), should they exist.

We could also introduce a "disambiguator" infobox; where there are 
duplicate names on different objects, we could say "You might also be 
interested in onfoo on this other object" (or words to that effect).

Regards-
-Doug

On 2/13/13 5:34 PM, Scott Rowe wrote:
> Consider the IDBTransaction onerror event. It fires not on the
> IDBTransaction error event, but on the DOMError event.
>
> Do you propose to remove the onerror event handler property from the
> IDBTransaction object, and assume that by providing the DOMError doc
> with a checkbox that the user of IDBTransaction will just "know" that
> there is an event handler in IDBTransaction for the error event?
>
> I think that is a dangerous assumption, as it relies on "implicit"
> knowledge. We achieve greater clarity if we are explicit about which
> events the object handles.
>
> Even though the IDBTransaction object does have an error property, which
> returns the DOMError event, without the onerror event handler,
> explicitly, the developer does not know how to name the function that
> handles the DOMError event.
>
> No, folks, our job is not to make it easier to document these APIs. Our
> job is to make them easier to use - even for novices who are not yet
> steeped in the JavaScript event handling model. This is why we follow
> the specifications to the letter, we do not take shortcuts to please
> ourselves, and we are explicit about every object in the model and how
> it is used. I strongly recommend we keep it that way.
>
> +Scott
>
>
>
> On Wed, Feb 13, 2013 at 1:01 PM, Lance Leonard
> <Lance.Leonard@microsoft.com <mailto:Lance.Leonard@microsoft.com>> wrote:
>
>     We had a similar conversation when we reorganized our content and
>     ended up combining the property page with the event page[1].
>
>     The general thinking was that it was easier on the novice to have a
>     single page to land on using search than to maintain separate pages
>     with similar content.
>
>     I'm fine either way, but do tend to prefer simplifying a
>     presentation when it makes sense to.
>
>     Hope this helps...
>
>     -- Lance
>
>     Links:
>
>     [1] - The current version of the abort event from MSDN:
>     http://msdn.microsoft.com/en-us/library/ie/ms536785(v=vs.85).aspx
>
>     -----Original Message-----
>     From: Chris Mills [mailto:cmills@opera.com <mailto:cmills@opera.com>]
>     Sent: Wednesday, February 13, 2013 11:56 AM
>     To: PhistucK
>     Cc: Julee; Scott Rowe; public-webplatform@w3.org
>     <mailto:public-webplatform@w3.org>
>     Subject: Re: A categorization/placing problem - event/property pages
>
>     This kind of approach would make sense to me, however I will defer
>     decision making/handling of these to the professionals (i.e. Scott)
>     in future ;-)
>
>     Chris Mills
>     Opera Software, dev.opera.com <http://dev.opera.com>
>     W3C Fellow, web education and webplatform.org
>     <http://webplatform.org> Author of "Practical CSS3: Develop and
>     Design" (http://goo.gl/AKf9M)
>
>     On 13 Feb 2013, at 18:49, PhistucK <phistuck@gmail.com
>     <mailto:phistuck@gmail.com>> wrote:
>
>      > When I posted about this (among other issues) a few months ago, I
>     think the initial conclusion was that we should only have event
>     pages (abort) and have a check box in the event template in order to
>     specify whether it may function as a property (onabort) and another
>     check box in the event template in order to specify whether it may
>     function as a standard event listener
>     (object.addEventListener("abort", handler, false)).
>      >
>      > I think having two (or more, if you include the dreadful inline
>     HTML event listeners) pages for most events is wasteful.
>      > Perhaps we should also have a check box for its inline HTML event
>     listeners attribute and a field for the HTML element, I do not know.
>      >
>      > ☆PhistucK
>      >
>      >
>      > On Wed, Feb 13, 2013 at 8:39 PM, Julee <julee@adobe.com
>     <mailto:julee@adobe.com>> wrote:
>      > Is there any place where we are drawing the relationship between
>     html element attributes (onerror), object properties (onerror),
>     events (error), and event listeners (error, handler)?
>      >
>      > Or are we planning on separating out each manifestation and
>     documenting them separately?
>      >
>      > Thanks much.
>      >
>      > Julee
>      > ----------------------------
>      > julee@adobe.com <mailto:julee@adobe.com>
>      > @adobejulee
>      >
>      > From: Scott Rowe <scottrowe@google.com <mailto:scottrowe@google.com>>
>      > Date: Wednesday, February 13, 2013 9:48 AM
>      > To: Chris Mills <cmills@opera.com <mailto:cmills@opera.com>>
>      > Cc: "public-webplatform@w3.org
>     <mailto:public-webplatform@w3.org>" <public-webplatform@w3.org
>     <mailto:public-webplatform@w3.org>>
>      > Subject: Re: A categorization/placing problem - event/property pages
>      >
>      > Hi Chris,
>      >
>      > Let me lend some perspective to this, in line...
>      > +Scott
>      >
>      >
>      > On Wed, Feb 13, 2013 at 9:03 AM, Chris Mills <cmills@opera.com
>     <mailto:cmills@opera.com>> wrote:
>      > Hi all,
>      >
>      > I am mailing to discuss a consistency problem we have come up
>     against in the properties/events pages on webplatform.org
>     <http://webplatform.org>; I have been discussing this with Frederic
>     Hemberger, who took part in the Berlin doc sprint. The question is,
>     how to categorise properyy and event pages.
>      >
>      > Crawling through the properties list
>     (http://docs.webplatform.org/w/index.php?title=Category:API_Object_Properties)
>     we have 40 event related properties:
>      >
>      > apis/file/properties/onabort
>      > apis/indexeddb/IDBTransaction/onabort
>      > apis/webrtc/RTCPeerConnection/onaddstream
>      > apis/webrtc/MediaStreamTrackList/onaddtrack
>      > apis/webaudio/ScriptProcessorNode/onaudioprocess
>      > apis/indexeddb/IDBOpenDBRequest/onblocked
>      > apis/indexeddb/IDBVersionChangeRequest/onblocked
>      > apis/appcache/ApplicationCache/oncached
>      > apis/appcache/ApplicationCache/onchecking
>      > apis/indexeddb/IDBTransaction/oncomplete
>      > apis/webrtc/RTCPeerConnection/ondatachannel
>      > apis/appcache/ApplicationCache/ondownloading
>      > apis/webrtc/MediaStream/onended
>      > etc.
>      >
>      > First, to level-set here, these are termed "event handlers" and
>     treated in the specifications as properties. We've followed suit in
>     the API docs.
>      >
>      >
>      > (Also, the File API is the only API listing those as
>      > "apis/file/properties/<propertyName>" instead of
>      > "apis/file/<propertyName>".)
>      >
>      > This was a mistake. This property belongs to the msStreamReader
>     object, and it's page is now located properly at
>     apis/file/MSStreamReader/onabort.
>      >
>      > However, it may be argued that all of the Microsoft-proprietary
>     documentation should be removed from WPD as it is not standard. But
>     that's an issue for a separate thread.
>      >
>      >
>      > On the other hand, the event page lists 54 API (61 if you include
>     SVG) and 107 DOM event pages, rather than their related properties.
>      >
>      > The questions is, how should we make these more consistent?
>      >
>      > DOM events and API object events are treated differently.
>     Consistency would confuse the issue rather than clarify.
>      >
>      >
>      > 1. We could list these as event pages primarily, but then have
>     another
>      > page for the event property in each case. So for example
>      >
>      > http://docs.webplatform.org/wiki/apis/file/events/onabort could
>     be the
>      > main page, with all the info on the event and its related property
>      > (but we'd be best changing onabort to abort)
>      >
>      > No. Under no circumstance should we change the names of API
>     object properties. These are defined in the spec. The event is
>     "abort," the event handler is "onabort."
>      >
>      > Incidentally, the "abort" event has yet to be documented. We're
>     on it.
>      >
>      >
>      > http://docs.webplatform.org/wiki/apis/file/properties/onabort could
>      > just have a minimum of information on it, but point to the above page
>      >
>      > 2. We could do basically the same, but have the property pages as
>     the main pages, and point the event pages to those.
>      >
>      > 3. We could just have the event pages, and make them cover both
>     the properties and events:
>      >
>      > http://docs.webplatform.org/wiki/apis/file/events/abort
>      >
>      > And maybe have a silent redirect on the similar property page.
>      >
>      > We (myself and Frederic) would rather go with moving the 40odd
>     existing property pages to the Events listing and not treat them as
>     "real" properties for the sake of documentation consistency
>     (although this might be less precise from an implementation point of
>     view).
>      >
>      > The way we are currently representing events and event handlers
>     in the API documentation is correct. We maintain the structure
>     prescribed in the specifications.
>      >
>      >
>      > Otherwise, we'd need to move all API events to properties (if you
>     think of DOM events as a "special breed"), and/or make duplicate (or
>     at least very similar) pages. We are more interested here in what is
>     most implementable/findable, rather than what is most technically
>     correct.
>      >
>      >
>      > DOM events, on the other hand, do appear to warrant a different
>     treatment, particularly because they are shared across many
>     different objects.
>      >
>      >
>      >
>      > Thoughts?
>      >
>      > Chris Mills
>      > Opera Software, dev.opera.com <http://dev.opera.com>
>      > W3C Fellow, web education and webplatform.org
>     <http://webplatform.org> Author of "Practical
>      > CSS3: Develop and Design" (http://goo.gl/AKf9M)
>      >
>      >
>      >
>      >
>
>
>
>
>

Received on Thursday, 14 February 2013 08:03:26 UTC