JavaScript：将JSDoc移到代码之外

Question

我希望你可以从Angular的角度出发担任翻译工作（但任何建议都会有所帮助）。我在我的函数上使用了JSDoc，但这使得代码看起来很混乱。我只是想知道是否有一种方法将JSDoc移动到某种外部文件中。

以下是我的JSDoc示例：

/**
* Does a GET call on the service MyGetCall
* @param {string} pUserID - 1st Parameter: User Login ID
* @param {string} pPassword - 2nd Parameter: User Password
* @returns The Call's Http Observable (subscribe to this function).
* @example this.flowservice.MyGetCall('Johnny', 'MySuperSecretPassword')
*              .subscribe(response => {
*                  console.log(response)
*              });
*/
MyGetCall(pUserID: string, pPassword: string): Observable<any> {
    const temp = this.httpclient.get<JSON>(`http://XXX/MyGetCall?userid=${pUserID}&password=${pPassword}`, {headers: this.headers});
    return temp;
}

因此，在这个例子中，我希望删除所有的JSDoc，并将其放入某种外部文件(jsdocs.xxx)中。这个文件可能会像这样:

MyGetCall:
    /**
    * Does a GET call on the service MyGetCall
    * @param {string} pUserID - 1st Parameter: User Login ID
    * @param {string} pPassword - 2nd Parameter: User Password
    * @returns The Call's Http Observable (subscribe to this function).
    * @example this.flowservice.MyGetCall('Johnny', 'MySuperSecretPassword')
    *              .subscribe(response => {
    *                  console.log(response)
    *              });
    */

MyOtherFunction:
    ...

MyOtherOtherFunction:
    ...

然后我可以在某个地方导入这个文件（jsdocs.xxx），让它能够与我的应用程序一起工作。对于使用过 JSDoc 的任何人，我希望这是有意义的。

- Paul Kruger

---

也许你可以使用这个插件将示例移动到源文件之外：https://github.com/jugglinmike/jsdoc-external-example - Sercan özen

啊，这很酷。谢谢！但当然，这还没有真正解决问题。 - Paul Kruger

你可以在任何地方添加jsdoc注释。如果它们不是紧挨着一个函数或方法，解析器就不能知道它是一个独立的函数，所以你可以在独立的注释中添加@function <函数名称>标签。 - garlon4

@ garlon4，您能否添加一个答案并提供一个示例呢？我似乎无法让这个想法起作用。 - Paul Kruger

也可以查看这个答案：https://dev59.com/M1gQ5IYBdhLWcg3wLg45 - Sebastian Norr

Answer 1

如果我要内联地记录一个类方法，可以这样做：

/**
 * @class 
 * @alias fileReader
 */
function fileReader() {
  /**
   * Tells the caller if it can handle the given file by returning a boolean.
   *
   * @param {File} file A `File` object.
   * @returns {boolean} `true` if this reader can read a file.
   */  
  this.canRead = function (file) {
    ...
  };
}

取而代之，我可以在其他地方记录我的方法：

/**
 * @class 
 * @alias fileReader
 */
function fileReader() {
  this.canRead = function (file) {
    ...
  };
}

文档可以存在不同的文件中，例如：

/**
 * Tells the caller if it can handle the given file by returning a boolean.
 *
 * @function canRead
 * @memberof fileReader
 * @instance
 * @param {File} file A `File` object.
 * @returns {boolean} `true` if this reader can read a file.
 */  

@function 参数定义了函数的名称，如果 jsdoc 没有立即跟随一个实际函数。 @memberof 告诉它父类或命名空间。 @instance 表示这是一个需要已实例化类的方法。

对于您的示例，我猜文档将会是：

/**
* Does a GET call on the service MyGetCall
* @function MyGetCall
* @memberof flowservice
* @instance
* @param {string} pUserID - 1st Parameter: User Login ID
* @param {string} pPassword - 2nd Parameter: User Password
* @returns The Call's Http Observable (subscribe to this function).
* @example this.flowservice.MyGetCall('Johnny', 'MySuperSecretPassword')
*              .subscribe(response => {
*                  console.log(response)
*              });
*/

- garlon4

---

你如何包含外部文件？ - Purefan

Answer 2

如果你希望Intellisense能够识别你的类型，那么这个答案主要适用于VS Code。

我成功地通过在typedefs.js文件中创建我的类型，并使用ts/vscode import(path/to/file).Foo标签引用该类型来实现。

JSDoc默认不支持此语法，因此建议还使用jsdoc-tsimport-plugin来解析你的文档。

例如：typedef.js：

/**
 * @typedef {Object} Foo
 * @property {string} id
 */

/**
 * @typedef {Object} Bar
 * @property {string[]} things
 */

// having to export an empty object here is annoying, 
// but required for vscode to pass on your types. 
export {};

coolFunction.js

/**
 * This function is super dope
 * @param {import('../typedef').Foo} foo - a foo
 * @return {import('../typedef').Bar} bar - an array of bars
 */

 export function (foo) {
    // do cool things
    return bar;
 }

- ccarvalhaes