search

csnover / js-doc-parse

An experimental library for parsing JavaScript files and extracting inline documentation.
31 stars 7 forks source link

Add support for documenting attach points and attach events #75

Open dylans opened 11 years ago

dylans commented 11 years ago

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 commented 11 years ago

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 commented 11 years ago

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