javascript - JSDoc3 不会生成指向 NodeJS 中 namespace 的超链接

Question

我敢打赌这是一个愚蠢的问题，但不知何故，我在今天早上找到的任何文档中都找不到原因。

我在使用 JavaDoc 方面经验丰富，但不知何故，即使 @link 的语法相同，JSDoc3 根本不会生成相关元素的 href。我已经尝试了命名空间链接的所有可能方法(也显然是错误的)，但没有一个对结果有任何改变。我希望通过编写 {@link #myFunction} 或至少 {@link MyClass#myFunction} 来接收链接，但这都没有创建超链接。这是我测试过的代码:

/**
 * See {@link myOtherFunction} and [MyClass's foo property]{@link MyClass#foo}.
 * Or look at {@link https://github.com GitHub}
 */
function myFunction(){};

/**
 * See {@link #myFunction} or maybe {@link #myFunction()}
 */
function myOtherFunction() {};

我使用 ./node_modules/.bin/jsdoc ./* --configure ./conf.json 生成它，我的默认配置文件是:

{
    "tags": {
        "allowUnknownTags": true
    },
    "source": {
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    },
    "plugins": [],
    "templates": {
        "cleverLinks": true,
        "monospaceLinks": false,
        "default": {
            "outputSourceFiles": true
        }
    }
}

(如果我写 "cleverLinks": false, 也没有什么区别)

这就是我的输出:

正如我们所看到的，URL 已正确生成，但命名空间却未正确生成。

我只是非常困惑，因为我无法找到必须执行某些操作才能生成命名空间的 href 的描述。另外 jsdoc 说:

The {@link} inline tag creates a link to the namepath or URL that you specify. When you use the {@link} tag, you can also provide link text, using one of several different formats. If you don't provide any link text, JSDoc uses the namepath or URL as the link text.

听起来不需要做任何事情来生成名称路径的链接。

它还将语法定义为:

{@link namepathOrURL}
[link text]{@link namepathOrURL}
{@link namepathOrURL|link text}
{@link namepathOrURL link text (after the first space)}

我的名称路径也没有问题，因为 webstorm 能够直接解析它们。

我到底错过了什么？

最诚挚的问候，织女星

Answer 1

我发现我的问题与 JSDoc 与 CommonJS (NodeJS) 的使用有关。经过几个小时的谷歌搜索和反复试验，我终于明白了它在 NodeJS 中的不同工作方式。我可能会使用 @inner 和 @instance 但这解决了为什么 JSDoc 不想为我的 NodeJS 代码生成链接的问题。

这是由于 CommonJS 的作用域与客户端 JS 的工作方式不同，其中一个原因在于 NodeJS 模块的定义。因此，我们需要告诉 JSDoc 如何通过为模块添加 @module 标签来解析变量，并通过解析其关系来引用模块的成员，例如 {@link module:MODULE_NAME~instanceName }.

这里是一个带有相应生成的 html 的示例。希望这可以帮助像我一样遇到同样问题的人。

最诚挚的问候，

织女星

/**
 * @module lib
 */

/**
 * @constructor
 */
var SomeClass = function () {

};

/**
 * Some doc...
 */
var moduleFunction = function () {

  /**
   * @type {number}
   */
  var innerVar = 0;

  /**
   * @type {number}
   */
  this.instanceVar = 0;

  /**
   * @memberOf module:lib~moduleFunction
   */
  function staticVar() {
    console.log(0)
  }
}

/**
 * Link to this module (identified by @module lib in the beginning): {@link module:lib} <br/>
 * Link to my constructor: {@link module:lib~SomeClass} <br/>
 * Link to a module function: {@link module:lib~moduleFunction} <br/>
 * Link to an instance variable of a module function: {@link module:lib~moduleFunction#instanceVar} <br/>
 * Link to a inner variable within a module function: {@link module:lib~moduleFunction~innerVar} <br/>
 * Link to a static variable within a module function: {@link module:lib~moduleFunction.staticVar} <br/>
 */
function documentedFunction(){}

<小时/>