Add support for documenting attach points and attach events

[dylans]

When creating widgets, it's often difficult to track the various items that are specified in the HTML templates. It would be nice to determine a mechanism for documenting the existing of these values in the HTML template, and parsing them in a useful manner for the API viewer.

[wkeese]

I've thought about documenting attach points too. One question is what you mean by "attach points". Just data-dojo-attach-point in templates, or any properties that map to widget DOMNodes, regardless of how the widget was created? I would think the latter would be more useful, since for example dojox/mobile widgets often have hand-crafted buildRendering() methods.

I've also thought about adding properties to widget prototypes corresponding to every attach point. We already have that for containerNode and domNode, but not for other properties.

As for attach events, that's stranger to document since it isn't part of the API of the widget, and doesn't correspond to anything we display in the API viewer.

[neonstalwart]

to doc any property that maps to a node (in a template or not), the simplest solution might be:

declare( ... , {
    /*=====
    // focusNode: DomNode
    //    a summary of the node
    focusNode: null,

    // valueNode: DomNode
    //    something about valueNode
    valueNode: null,
    =====*/

    ...
});

so then the code isn't bloated with property names that don't need to be declared on the prototype but they can still be documented as part of the public API.

i'm probably with @wkeese on attach events

• i don't see why they matter. they are a way to direct events into the widget and so aren't relevant to what is provided by the widget as part of it's public API
• i don't know how you'd document them if they did matter