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

【问题标题】：JSDoc3 does not generate hyperlinks to namespaces in NodeJSJSDoc3 不会生成指向 NodeJS 中命名空间的超链接
【发布时间】：2018-04-28 21:20:42
【问题描述】：

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

我在使用 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 能够直接解析它们。

我到底错过了什么？

最好的问候，维加啊

【问题讨论】：

标签： javascript node.js jsdoc3

【解决方案1】：

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

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

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

最好的问候，

Vegaaaa

/**
 * @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(){}

【讨论】：