如何在 JSDoc 中使用 @borrows 标签

Question

我一直很难让 @borrows 标签在 JSDoc 中工作。我一直在尝试从一个函数获取文档，并将其用作第二个函数的文档。但我似乎连一个简单的例子都无法运行！

/**
 * This is the description for funcA
 */
var funcA = function() {};

/**
 * @borrows funcA as funcB
 */
var funcB = function() {};

我期望这两个函数能够输出完全相同的文档。然而只有 funcA 只有描述。

Answer 1

@borrows

标签似乎不能直接作用于符号，而只能间接作用。 例如我有：

/** does amazing things */
function origFunc = function() {};

/**
 * @borrows origFunc as exportedFunc
 */
exports.exportedFunc = origFunc;

但是我和你一样，在生成的文档中没有得到任何有用的信息。

那似乎是因为

@borrows

标签在 容器 上运行。 （如果您在示例中注意到

@borrows

标签位于“util”模块/命名空间上，而不是重命名的符号上。）

所以这对我有用：

/** does amazing things */
function origFunc = function() {};

/**
 * @borrows origFunc as exportedFunc
 */
exports = {
  exportedFunc: origFunc,
}

看起来像是

@borrows

中的一个错误。 （或者至少是文档中的错误。）

Answer 2

我最近使用了它，我想做的是创建一个模块并向其添加一些功能。问题是我没有任何与该模块直接相关的内容，因为导出只是一行。这就是我最终使用

@borrows

的方式。

/**
 * A typehead with options filtered by user input.
 *
 * @module Typehead
 * @borrows Typehead
 * @borrows TypedOption
 * @example
 * <Typehead />
 */
export { default } from './Typehead'

在这种情况下，根据

Typehead

的种类，

Function

将被借用在模块页面的

Classes

或

Typehead

部分，并且它将显示在

@example

渲染下。

注意：但是

@borrows

会向系统添加一些额外的条目，经过一些实验，也许

@see

是更好的用途。

Answer 3

我不知道这是否有帮助，但这对我有用：

// @filename fn.mjs

/** #1
 * This documentation is shared for both `import fn from '...'` and `import {fn} from '...'`.
 */
export const fn =
(
  /** #2
   * This documentation is only available when `fn` is properly called.
   */
  arg =>
  {
    // ...
  }
)
export default fn; // This must follow `export const ...` that is defaulted with no comments between.

// @filename fn.test.mjs

import FN, { fn } from './fn.mjs'

// Shows documentation #1
FN;
fn;

// Shows documentation #2
FN();
fn();

// You can even alias the thing...
import { fn as StillDocumented } from './fn.mjs';

// Shows documentation #1
StillDocumented;

// Shows documentation #2
StillDocumented();

为此您不需要

@borrows

标签。具有挑战性的任务是在类定义中借用文档...对于每个回收的类

fn

，您必须在其访问器中放置一个文档...解决方法如下：

class Anything
{
  /**
   * #3
   */
  get fn ()
  {
    return fn;
  }
};

// TypeError: not a function.
Anything.prototype.fn();

// Fast usage, no error, but inherits documentation #3 and #2 only.
(Anything.prototype.fn)();
// Hover over `.fn` and you get #3.
// Type the `()` and you get #2.

/**
 * #4
 */
const FN = Anything.prototype.fn;

// Shows documentation #4
FN;

// Shows documentation #2
FN();