【问题标题】：JsDoc NamespaceJsDoc 命名空间
【发布时间】：2017-06-08 07:50:08
【问题描述】：

我正在用 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!
}

然而，

不显示第一个函数的文档。
已创建车间命名空间
Workshop.doIt 仅通过其描述记录，参数不是
Workshop.flyNow 有据可查

有人知道为什么吗？

谢谢！

【问题讨论】：

标签： javascript documentation jsdoc

【解决方案1】：

原因如下：

1.

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

/** * @namespace Array */

您可以按如下方式改进函数的文档：

/**
 * 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 标签修复：

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

结果如下所示：

【讨论】：

【解决方案2】：

Array 是否作为符号存在？如果不是，那么这就是没有记录的原因。

关于参数，您确定* 是有效类型吗？可以试试Object吗？

【讨论】：

【解决方案3】：

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

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

/**
 * Does something great
 * @param {*} plep - My super param!
 */
function myfunc(plep){
    // does something
}

/**
 * Does something great
 * @param {*} plep - My super param!
 * @function
 */
var alternativeDoIt = function myfunc2(plep){
 // does the same thing
}

/**
 * Workshop Namespace
 * @namespace
*/

var Workshop = {};


/**
* Does something great 2
* @function (<== check if this is useful)
*/
Workshop.doIt = myfunc;

Workshop.doIt2 = alternativeDoIt;

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

【讨论】：