JSDoc3 不生成指向 NodeJS 命名空间的超链接

Question

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

我有使用 JavaDoc 的经验，但不知何故，即使 @link 的语法相同，JSDoc3 也不会生成相关元素的 href。我已经尝试了所有可能的命名空间 link 方法（也显然是错误的），但没有一种方法会稍微改变结果。我希望通过写 {@link #myFunction} 或至少 {@link MyClass#myFunction} 来接收 link，但这两者都没有创建 hyperlink。这是我测试过的代码：

/**
 * 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.

这听起来并不需要做任何事情来为名称路径生成 links。

它还将语法定义为：

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

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

我错过了什么？

此致， Vegaaaa

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

JSDoc3 不生成指向 NodeJS 命名空间的超链接

JSDoc3 does not generate hyperlinks to namespaces in NodeJS

javascript

node.js

jsdoc3