JSDoc3 不会生成指向 NodeJS 中名称空间的超链接

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 说：

{ @link } 内联标记创建指向您指定的名称路径或 URL 的链接。当您使用 { @link } 标记时，您还可以使用几种不同格式之一提供链接文本。如果您不提供任何链接文本，JSDoc 将使用名称路径或 URL 作为链接文本。

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

它还将语法定义为：

{@link namepathOrURL}
[链接文本]{@link namepathOrURL}
{@link namepathOrURL|链接文本}
{@link namepathOrURL 链接文本（第一个空格之后）}

我的名称路径也很好，因为 webstorm 能够直接解析它们。

我这么想念什么？

最好的问候，Vegaaaa

Answer 1

我发现我的问题与 JSDoc 与 CommonJS (NodeJS) 的使用有关。经过几个小时的谷歌搜索和反复试验，我终于明白了它在 NodeJS 中的不同工作方式。我可能会使用@innerand @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(){}