Question

我主要是从角度角度来问这个问题（但是任何建议都会有所帮助）。我的函数上有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.
 */

如果jsdoc后面没有实际的函数，则@function参数定义函数的名称。 @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)
*              });
*/

Javascript：将JSDoc移出代码

1 个答案: