标签: jsdoc3

我有一个返回构造函数的 javascript 函数（请参阅下面的代码示例）。我将如何使用 jsdoc 的 @returns 标签来记录这一点。执行 @returns {MyConstructor} 似乎不正确，因为这意味着我返回的是“MyConstructor”的实例而不是构造函数本身，对吗？

function MyConstructor() {
    var self = this;

    self.myFunction = function() {
        return true;
    };

    self.getMyFunctionResult = function() {
        return self.myFunction();
    };
}

/**
 * @returns {?} A constructor that will be instantiated
 */
function getConstructor() {
    return MyConstructor;
}

var constructor = getConstructor();
var instance = new constructor();

JSDoc 3的文档包括以下示例:

/**
 * The complete Triforce, or one or more components of the Triforce.
 * @typedef {Object} WishGranter~Triforce
 * @property {boolean} hasCourage - Indicates whether the Courage component is present.
 * @property {boolean} hasPower - Indicates whether the Power component is present.
 * @property {boolean} hasWisdom - Indicates whether the Wisdom component is present.
 */

/**
 * A class for granting wishes, powered by the Triforce.
 * @class
 * @param {...WishGranter~Triforce} triforce - One to three {@link …

请向我解释一下描述这个模块的最佳方法:

/**
 * Common util methods
 * @module Utils
 */
var Utils = (/** @lends module:Utils */
    function () {

    /**
     * Some default value
     * @constant
     * @public
     * @static
     * @type {string}
     */
    var staticConstantField = "Some value";

    //export to public access
    var exports = {
        staticConstantField: staticConstantField,
        getUrlArgs: getUrlArgs,
        isJSON: isJSON
    };

    return exports;

    /**
     * Return url arguments as associate array
     * @public
     * @static
     * @returns {Array} - url args
     */
    function getUrlArgs() {
        return …

我目前正在使用 JSDoc 记录我的一个 API。虽然这很有效，但真正让我烦恼的一件事是重复文档的出现。一个常见的例子是属性及其 getter 的文档：

function AClass() {
    /**
     * The current state of the object. Determines wether this object has been initialized yet.
     * @type {String}
     * @private
     */
    this._state = "initalized";
}

/**
 * Returns the current state of the object, which determines if the object has been initalized yet.
 * @return {String} The current state of the object
 */
AnObject.prototype.getState = function() {
    return this._state;
}

我想每个人都在这里看到了这个问题。该属性实际上被记录了三遍（私有属性本身、getter 方法描述和方法的返回值）。简单地将方法的描述更改为类似的Returns the state内容并不是一个真正的选择，因为我通常在文档输出中隐藏私有属性。

我对此类情况是否有最佳实践以及其他人如何处理很感兴趣。作为一个痴迷于 DRY 的人，似乎应该有更好的选择来处理这些情况。

我想知道是否可以从一个模块链接到另一个模块的属性/方法。

到目前为止，我已经尝试过但没有成功的方法：

/**
 * {@link module:modules/modulName#id}
 */

我的模块遵循以下模式：

/**
 * @module modules/modulName
 */
define(function() {

    'use strict';

    /**
     * @alias module:modules/modulName
     */
    var module = {
        /** Initialisation */
        init: function() {}
    };

    return module;

});

有没有办法实现我想要的？

我正在尝试在我的ES6项目中使用JSDoc,我正在返回一个Map:

/**
 * Some documentation.. 
 *
 * @returns {undefined} <- This should be replaced
 */
function returningMap() {
    const someMap = new Map();
    someMap.set("key", {a, b, c});
    return someMap;
}

我该如何记录@returns？

没有很好的答案在这里.

有没有办法对jsdoc中带有“+”等特殊符号的属性进行正确的描述？

例子：

/**
  * @typedef {Object} TestObject
  * @property {string} "id+name"
  */

在这种情况下，“id+name”似乎是无效语法。

我有以下用于包装构造函数的高阶函数：

/**
 * Wrapper for calling constructor with given parameters
 *
 * @param {Class} Cls
 * @returns {function} Wrapper on constructor which creates an instance of given Class
 */
function constructorWrapper(Cls) {
    return (...args) => new Cls(...args);
}

因此，如果我有一个 class MyClass，我可以执行以下操作：

exports.MyClass = MyClass;
exports.myClass = constructorWrapper(MyClass);

现在可以通过以下两种方式在导入后实例化该类：

const instance1 = new MyClass(param1, param2);
const instance2 = myClass(param1, param2);

在 vscode 中，instance1会有智能感知支持，但instance2不会。如何记录函数/导出以便使用包装器创建的对象被识别为类的实例？

我对 npm 和 jsdoc 有问题。这个问题类似于但不相同：如何获取我的 npm 模块的 JSdoc 文档，以便在用户的 VScode 中显示函数？就我而言，如果将代码安装在本地文件夹中，则会出现 jsdoc 信息。当我使用 npm install 并且代码安装在 node_modules 中时出现问题。

我创建了一个 npm 模块，它使用类似 SQL 的命令（插入、选择、更新等）来标准化对 couchdb 和 cloudant 的访问。每个函数都以 jsdoc 注释开头，但是require(rddill/cloudant当一个人悬停在它上面时，这个模块就显示出来了"any".

• 模块顶部的代码（index.js）：

/**
 * CoachCloudant module
 * @module rddill/cloudant
 */

'use strict';
let request = require('request');
let fs = require('fs');
let path = require('path');

module.exports = {
  cloudantAuth: {},
  noSQLCreds: {},
  _credentials: {},

  /**
  * add code to handle IAM based authentication.
  * use test to …

鉴于以下代码，我如何正确记录使用最新的 JSDoc？

function docMe([foo, bar = null, baz = 1]) { 
  /* */ 
}

我试过这个：

/**
 * @param {Array} options Array containing the options.
 * @param {HTMLElement} options[0].foo An HTML element.
 * @param {Object} [options[1].bar] An object.
 * @param {Number} [options[2].baz] A number.
 */

显然这是行不通的，JSDoc 文档提到的只是如何记录解构的对象参数，而不是解构的数组参数。