senchalabs/jsduck — Issue #76: Support for documenting overrides
Author: nene
Created: 2011-10-17 12:45:30+00:00
State: open

From Don:

I was thinking more about this and realized that we probably need some support from our jsdoc to properly handle overrides. In the case of Element, it would be best if the required overrides had the docs injected into Element. To the user, ideally only Element is exposed (not AbstractElement or artifacts of implementation).

There is likely going to need to be some @tags added, like @override.

As a straw-man starting point, what about this:

/**
* @override Ext.rtl.Element
* @class Ext.dom.Element
*
* Blah blah blah RTL, blah blah.
*/
Ext.define('Ext.rtl.Elemement', {
override: 'Ext.dom.Element',

...
});

The tool may not need @class or even @override if the structure of the code is vanilla (no wrapping functions or such). I suppose these override chunks could be turned into grouping/heading areas in the doc. Overrides probably also need the ability to have a dedicated place in the doc. Aria and RTL for example would, while the Element parts would not. Maybe we have a @nodoc tag or something already.

The optimal solution on the docs side is one I am happy to let others ponder, but wanted to get the ball rolling and avoid last minute surprises.

It's magic is its interaction with build such that the override is not included unless the class it overrides is included.

Anyway, the first two places we are planning to use it in 4.1 (Aria and RTL support) might also benefit from both adding to the target class and being able to tell that the config property or method is provided by a separate override. This could be addressed other ways and these topics probably need their own Guide so we may just past links to the Guide in each method/property.

For example, RTL support will be used like this (roughly):

Ext.define('My.app.App', {
requires: [
'Ext.rtl.*' // this might be encapsulated TBD
]
});

//--

Ext.define('My.app.View', {
extend: 'Ext.Viewport',
rtl: true, // config added by RTL

...
});

The details are still in flux here, but the idea is that the 'rtl' config is added to AbstractComponent by the Ext.rtl.AbstractComponent override. In this way, RTL support take no space in the build unless you require it.

The temptation would be to have some simple mechanism to indicate this on the 'rtl' config property so users know they must include RTL support for it to work. Similar things will be true for Aria support.