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> wrote:

> Hi all,
>
> I am mailing to discuss a consistency problem we have come up against in
> the properties/events pages on 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<http://docs.webplatform.org/wiki/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
> W3C Fellow, web education and webplatform.org
> Author of "Practical CSS3: Develop and Design" (http://goo.gl/AKf9M)
>
>
>