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 的任何人，我希望这是有道理的。

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)
*              });
*/