Re: DOM API Docs Reorganization

Thanks Alex, this raises an interesting issue.

tl;dr: I don't think this would force a change in the way we structure the
URLs, but the solution should be part of the DOM structure widget that
Julee proposes, and it informs how we might design that widget. Read on!

We do have the inheritance provided for already. However, it is limited to
inheritance from the immediate parent node. So, for example, in the
dom/Element page [1], the appendChild method is shown under the Inherited
from Node heading.

Not so, however, with the dom/HTMLElement page [2], where only those
members Inherited from Element are shown. Likewise, to take it a step
further, on the dom/HTMLMenuElement page [3], only the members inherited
from HTMLElement are shown.

But, boy-howdy, how long the page would be if we nested every member that
inherited through the chain! And the larger question is, how useful would
this be?

True, we are relying on the reader to follow the links back up the chain,
and this is not straight-forward. If she/he does not find appendChild in
the HTMLMenuElement object, we implicitly expect her/him to click the link
back up to HTMLElement, skip those members belonging to HTMLElement (since
she/he has already seen the members it bequeathed to HTMLMenuElement), and
scan through the methods inherited from Node, before finally shouting
Eureka!

But that's not the most likely scenario under which a user is trying to
learn whether she/he can use appendChild on an HTMLMenuElement. Instead,
she/he would visit the appendChild page [4], looking for a list of DOM
objects that support the method.

We could easily accomplish this with some magic that just displays the
inheritance structure in the page. So, where  it currently reads:

*Method of dom/Node*

The page would instead read:

*Method of the following objects:*
*dom/Node *
* > dom/Element*
*   > dom/HTMLElement*
*     > dom/HTMLMenuElement*

That probably wouldn't be too hard to accomplish, and within the scope of
Julee's proposed DOM structure widget work. The mechanism above would
provide for the relevant DOM structure on every page, greatly enhancing the
"Inherits from" feature, and potentially allowing us to eliminate the
redundant tables of inherited members in each object page.

Instead, we would just add a note to the page saying, "if you don't see a
method here, look in the object's parent" or something. Note that this
presupposes that all objects inherit all members of their parents, which is
how I understand the DOM: if the object inherits from Node, it has all of
the Node members - unless I nodded off and missed something.

Also, we have a similar problem with the relationship between HTML elements
and the attributes they support. When the user visits an HTML element page,
she/he should see a list of attributes that the element supports (and
vice-versa when visiting an attribute page). Right now, she/he is out of
luck. But I digress.

Point is, our current architecture is a long ways away from ready for
prime-time. But from insightful (or incite-full) questions like yours,
we're making progress.

Thanks!

~Scott

[1] http://docs.webplatform.org/wiki/dom/Element
[2] http://docs.webplatform.org/wiki/dom/HTMLElement
[3] http://docs.webplatform.org/wiki/dom/HTMLMenuElement
[4] http://docs.webplatform.org/wiki/dom/methods/appendChild



On Fri, Apr 26, 2013 at 12:27 PM, Alex Komoroske <komoroske@google.com>wrote:

> Hi Scott,
>
> Thanks for writing up this plan!
>
> Everything looks good to me, with one question: how would we handle things
> where a method/property is inherited by sub-classes?
>
> For example, appendChild is a method on Node, but Element, HTMLElement,
> ImgElement all inherit it. Presumably, it would live at
>  dom/Node/appendChild and then the reference pages for ImgElement (as an
> example) would just link to that page? Did I get that right?
>
> --Alex
>
>
> On Thu, Apr 25, 2013 at 9:16 AM, Eliot Graff <Eliot.Graff@microsoft.com>wrote:
>
>>  Hi Scott.****
>>
>> ** **
>>
>> While there’s always room for debate in any plan, I think that this one
>> is sound, and I am in favor of proceeding with it as you propose it.****
>>
>> ** **
>>
>> Thanks for being the champion for this.****
>>
>> ** **
>>
>> Eliot****
>>
>> ** **
>>
>> *From:* Scott Rowe [mailto:scottrowe@google.com]
>> *Sent:* Thursday, April 25, 2013 8:44 AM
>> *To:* public-webplatform@w3.org
>> *Subject:* DOM API Docs Reorganization****
>>
>> ** **
>>
>> We'd like to get going with reorganizing the DOM API pages, and before we
>> do, we need the community to bless the proposed methodology:****
>>
>> ** **
>>
>> http://docs.webplatform.org/wiki/WPD:Projects/DOM_API_docs****
>>
>> ** **
>>
>> Please have a look and provide any comments in this thread. We'll also
>> make time in the Friday conference call to discuss the proposal.****
>>
>> ** **
>>
>> We'd like to resolve this by the end of the day Friday (tomorrow) so we
>> can start work next week.****
>>
>> ** **
>>
>> Thanks!****
>>
>> ~Scott****
>>
>> ** **
>>
>
>