Re: DOM API Docs Reorganization

Note that the parent field supports listing methods/properties of multiple
ancestors already. For various reasons (already discussed on this list),
listing all properties/methods is extremely expensive in the general case.
The current solution allows you to explicitly configure how many levels of
the hierarchy to print out. This allows the authors of the content to
figure out how far up the chain it makes sense to go.


On Fri, Apr 26, 2013 at 2:02 PM, Scott Rowe <scottrowe@google.com> wrote:

> 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****
>>>
>>> ** **
>>>
>>
>>
>