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文档完整。

有人知道原因吗？

谢谢！

- Jo Colina

Answer 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标记来修复它：

/** * 做一些伟大的事情 * @param {*} plep - 我的超级参数！ * * @method */ Workshop.doIt = myfunc;

结果看起来像这样：

- Igwe Kalu

Answer 2

/**
 * 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!
}

- Buenjy

Answer 3

Array 作为符号存在吗？如果不存在，那就是这个未被记录的原因。

关于参数，你确定 * 是一个有效的类型吗？你可以尝试使用 Object 吗？

- SGD