- From: Janet Swisher <jswisher@mozilla.com>
- Date: Thu, 14 Feb 2013 12:36:09 -0600
- To: public-webplatform@w3.org
- Message-ID: <511D2E99.1050108@mozilla.com>
I don't know about the general case, but it seems like this particular
example is crying out for a conceptual article about error handling, and
the various entities involved, and how, when, and why they're used. Then
the reference articles about those entities can be organized according
to the spec structure, and can still be findable from the concept
article (and each other?).
On 2/14/13 12:01 PM, Scott Rowe wrote:
> Hmm. Let's not overlook the importance of semantics and structure
> here. Semantics matter. The onerror event handler is a property, a
> separate property of the IDBTransaction object. Structure matters. The
> onerror event belongs under the IDBTransaction object, not within or
> under the error property. You wouldn't write this:
>
> transaction.error.onerror = function(event) {
> // Do something
> };
>
> rather, this:
>
> transaction.onerror = function(event) {
> // Do something
> };
>
> Likewise, the documentation's structure, reflected in the URL, should
> look like this:
>
> apis/indexeddb/IDBTransaction/onerror
>
> not this:
>
> apis/indexeddb/IDBTransaction/error (with onerror hidden in this
> location)
>
> When the purpose of the URL is to describe the model.
>
> There are two reasons for following this methodology. First, we want
> other consumers of WPD to be able to use our documentation, without
> depending on some kind of lookup or reference intermediary. The most
> relevant example is the very use case we have in mind for the CSS
> properties - as content for the Chrome Developer Tools, which will
> find the relevant CSS property based on the property's URL.
>
> Looking forward, toward a tools use case for our APIs, when the user
> hits the tab key (or whatever), she should get a list that looks like
> this:
>
> IDBTransaction.<hits tab or whatever>
> db
> error
> mode
> onabort
> oncomplete
> onerror
>
> Also, hovering over that "onerror" will pop up a summary and a link to
> the documentation.
>
> In the absence of "onerror" from the model, are we expecting the user
> to hit the tab key, select "error" then backarrow over and insert the
> "on"? Are we expecting the user to "intuit" that the documentation
> for "onerror" will be found by hovering over the "error".
>
> Second, and likewise, to use the wiki's established content management
> paradigm: unambiguous organization
> (apis/indexeddb/IDBTransaction/onerror is what it is) and regardless
> of how the user finds this information, through search or navigation,
> she knows that this is the canonical location and description of the
> "onerror" event handler.
>
> As soon as we start pulling fast ones with our structure, folding
> related properties into single pages, we lose not only the ability to
> reference those separate properties but we build ambiguity into a
> model that, defined in the specifications, is designed to be
> unambiguous. We have to honor the API's design, not presume to take
> shortcuts with it.
>
> Do you really want to charge down the road of building a bunch of
> complicated templates and forms to make the model more complicated?
>
> +Scott
>
>
>
> On Thu, Feb 14, 2013 at 12:07 AM, Doug Schepers <schepers@w3.org
> <mailto:schepers@w3.org>> wrote:
>
> Hi, PhistucK-
>
> Yes, I think we all agree with this.
>
> Maintaining separate pages for the 'foo' event, the 'onfoo' object
> property, and the 'onfoo' attribute (where they are all
> equivalent) would not only be a maintenance nightmare, but would
> also be a bit inaccurate.
>
> Regards-
> -Doug
>
>
>
> On 2/14/13 3:02 AM, PhistucK wrote:
>
> I do not quite understand your example, sorry.
>
> Anyway, I meant that this check box should make the event
> appear as an
> onevent property on the page of the object (as part of drawing
> events,
> properties and methods), so the information will still be
> there and the
> links, events and properties will still be listed, but all of
> them will
> go to the same page (that includes the combined information)
> of that
> event. The template should, of course, have generic text for
> explaining
> all of the ways of adding that event listener (property, HTML
> attribute
> and addEventListener) that are supported for this event.
>
> I am not sure all of this is feasible, others may know, but I
> think this
> is the correct way to handle this situation.
> This also has the benefit of synchronizing the information,
> preventing
> it from being outdated in one page and up to date in another.
>
> It is a maintenance win and an accuracy win. Everyone is happy
> (except
> the one who has to implement this beast ;)).
>
> ☆*PhistucK*
>
>
>
> On Thu, Feb 14, 2013 at 12:34 AM, Scott Rowe
> <scottrowe@google.com <mailto:scottrowe@google.com>
> <mailto:scottrowe@google.com <mailto:scottrowe@google.com>>>
> 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 <tel:2013> at 1:01 PM, Lance Leonard
> <Lance.Leonard@microsoft.com
> <mailto:Lance.Leonard@microsoft.com>
> <mailto: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
> <http://msdn.microsoft.com/en-us/library/ie/ms536785%28v=vs.85%29.aspx>
>
> -----Original Message-----
> From: Chris Mills [mailto:cmills@opera.com
> <mailto:cmills@opera.com>
> <mailto:cmills@opera.com <mailto:cmills@opera.com>>]
> Sent: Wednesday, February 13, 2013 <tel:2013> 11:56 AM
> To: PhistucK
> Cc: Julee; Scott Rowe; public-webplatform@w3.org
> <mailto:public-webplatform@w3.org>
> <mailto: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>
> <http://dev.opera.com>
>
> W3C Fellow, web education and webplatform.org
> <http://webplatform.org>
> <http://webplatform.org> Author of "Practical CSS3:
> Develop and
> Design" (http://goo.gl/AKf9M)
>
> On 13 Feb 2013 <tel:2013>, at 18:49, PhistucK
>
> <phistuck@gmail.com <mailto:phistuck@gmail.com>
> <mailto: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 <tel:2013> at 8:39 PM, Julee
>
> <julee@adobe.com <mailto:julee@adobe.com>
> <mailto: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>
> <mailto:julee@adobe.com <mailto:julee@adobe.com>>
>
> > @adobejulee
> >
> > From: Scott Rowe <scottrowe@google.com
> <mailto:scottrowe@google.com>
> <mailto:scottrowe@google.com
> <mailto:scottrowe@google.com>>>
> > Date: Wednesday, February 13, 2013 <tel:2013> 9:48 AM
>
> > To: Chris Mills <cmills@opera.com
> <mailto:cmills@opera.com> <mailto:cmills@opera.com
> <mailto:cmills@opera.com>>>
> > Cc: "public-webplatform@w3.org
> <mailto:public-webplatform@w3.org>
> <mailto:public-webplatform@w3.org
> <mailto:public-webplatform@w3.org>>"
> <public-webplatform@w3.org <mailto:public-webplatform@w3.org>
> <mailto: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 <tel:2013> at 9:03 AM, Chris
> Mills
>
> <cmills@opera.com <mailto:cmills@opera.com>
> <mailto: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>
> <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> <http://dev.opera.com>
>
> > W3C Fellow, web education and webplatform.org
> <http://webplatform.org>
> <http://webplatform.org> Author of "Practical
>
> > CSS3: Develop and Design" (http://goo.gl/AKf9M)
> >
> >
> >
> >
>
>
>
>
>
>
>
>
>
--
Janet Swisher <mailto:jREMOVEswisher@mozilla.com>
Mozilla Developer Network <https://developer.mozilla.org>
Technical Writer/Community Steward
Received on Thursday, 14 February 2013 18:36:43 UTC