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}内联标记会创建指向您指定的名称路径或网址的链接。使用{@link}代码时，您还可以使用多种不同格式之一提供链接文字。如果您不提供任何链接文本，JSDoc将使用名称路径或URL作为链接文本。

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

它还定义了语法：

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

我的名称路径也可以，因为webstorm能够直接解决它们。

我错过了什么？

祝你好运， Vegaaaa

Answer 1

我发现我的问题与使用CommonJS（NodeJS）的JSDoc有关。经过几个小时的谷歌搜索和反复试验，我已经设法最终了解它在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(){}

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

1 个答案: