Javascript:将JSDoc移出代码 [英] Javascript: Move JSDoc's outside of code

问题描述

我主要是从角度角度来问这个问题(但是任何建议都会有所帮助).我的函数上有JSDoc，但它使代码看起来很凌乱.我只想知道是否有办法将JSDoc移到某种类型的外部文件中.

I ask this mostly from a Angular perspective (but any advice would help). I have JSDoc's on my functions but it makes the code look very messy. I would just like to know if there is a way to move the JSDoc's to some type of external file.

我的JSDoc的示例:

An example of my JSDoc's:

/**
* 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)中.然后，该文件将如下所示:

So in this example I would like to remove all the JSDoc's and put it in some kind of external file (jsdocs.xxx). This file would then look something like this:

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

Then I can import this file (jsdocs.xxx) somewhere for it to work with my app. For anyone that has used JSDoc's I hope this makes sense.

推荐答案

如果是内联的，我会记录这样的类方法:

If, inline, I would document a class method like so:

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

相反，我可以在其他地方记录我的方法:

Instead, I could document my method somewhere else:

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

文档可能位于另一个文件中，如下所示:

And the documentation could be in a different file, like so:

/**
 * 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说它是一种需要实例化类的方法.

The @function parameter defines the name of the function if the jsdoc isn't immediately followed by an actual function. The @memberof tells it the parent class or namespace. The @instance says that it is a method that requires an instantiated class rather.

以您的示例为例，我猜文档应该是

For your example, I'm guessing that the documentation would be

/**
* 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移出代码的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！