javascript - JsDoc 命名空间

Question

我正在使用 JsDoc 编辑 js 文件以获得干净的文档。我的结构非常简单:

/**
 * Finds an object
 * @param {string} prop - Property
*/

Array.prototype.findObject = function _findObj(prop, val){
    // blablabla
}


function myfunc(plep){
    // does something
}

/**
 * Workshop Namespace
 * @namespace
*/

var Workshop = {};


/**
 * Does something great
 * @param {*} plep - My super param!
*/
Workshop.doIt = myfunc;

/**
 * It works!
 * @param {string} fly - my flying param
*/
Workshop.flyNow = function _flyN (fly){
    // fly!
}

但是，

1. 未显示第一个函数的文档。
2. 已创建 Workshop 命名空间
3. Workshop.doIt 仅由其描述记录，参数没有
4. Workshop.flyNow 有据可查

有人知道为什么吗？

谢谢!

Answer 1

原因如下:

1.

第一个函数没有记录，因为它不属于任何可识别的命名空间。要解决此问题，您可以创建一个虚拟 namespace ，如下所示:


/**
* @namespace 数组
*/


并且您可以如下改进函数的文档:

/**
 * Finds an object.
 *
 * @param {string} prop Property name.
 * @param {string|number|function|object} val Value.
 *
 * @function findObject
 * @memberof Array#
 */
Array.prototype.findObject = function _findObj ( prop, val ) {
    // blablabla
}

结果如下

3.

没有记录参数，因为 JSDoc 解析器不能将 Workshop.doIt( ... ) 识别为函数。这可以用 @function 或 @method 标签修复:


/**
* 做了很棒的事
* @param {*} plep - 我的 super 参数!
*
* @方法
*/
Workshop.doIt = myfunc;


结果如下所示: