JSDoc inheriting parameter documentation

问题

Let's say I have two functions, where one extends the other.

/**
* @abstract
* @param {Object} settings
* @param {Number} settings.x
* @param {Number} settings.y
* 
*/
function Base(settings) {
    this.x = settings.x;
    this.y = settings.y;
}

/**
* @extends Base
*/
function Foo(settings) {
    Base.call(this, settings);    
}

These two functions are in two separate files. Is there any way I can inherit the parameter documentation from the Base function in my Foo function, or do I have to write the documentation twice?

I have tried making settings a @typedef like this:

/**
 * @typedef {Object} BaseSettings
 * @property {Number} x
 * @property {Number} y
 *
 */

/**
* @extends Base
* @param {BaseSettings} settings
*/
function Foo(settings) {
    Base.call(this, settings);    
}

But this just links to a global Type Definitions, and I want the parameter documented on the same page as the function. But is this even possible, without writing the documentation twice?

回答1:

I don't think this can be done. You can document it via @typedef as in your question but it will just link the type to it's definition. I'm not aware of a way of inlining a defined type.

回答2:

There is a way to inline define a subclass but i don't think it does help in this particular case. Anyway maybe it helps others:

/** 
 * @defines my.class
 */
function MyClass () {};

var mySubType = /** @lends my.class.prototype */{
    attribute: test
}

var result = myWhateverFunction(myVar, /** @lends my.class.prototype */{ subattr: 1 }) {
   return true;
}

This actually should work in any object literal scenario. We're using it in conjunction with a functional driven object inheritance framework (legacy dojo 1.10 declare) where you derive using an object literal within a function call

This way we can properly document the inheritance.

来源：https://stackoverflow.com/questions/29521446/jsdoc-inheriting-parameter-documentation

标签

jsdoc