Javascript: Move JSDoc's outside of code

Question

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.

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;
}

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:
    ...

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.

Perhaps you can use this plugin to move at least the examples to outside of source file: https://github.com/jugglinmike/jsdoc-external-example — Sercan özen, Aug 14 '18 at 15:55
Ah this is cool. Thank you! But of course this does not really solve the problem yet — Paul Kruger, Aug 15 '18 at 05:10
You can make jsdoc comments anywhere. If they aren't immediately adjacent to a function or method, the parser can't know that it is a function by itself, so you can add the `@function ` tag in the stand-alone comment. — garlon4, Aug 24 '18 at 14:04
@garlon4 Would you mind adding an answer please, with an example. I can't seem to get this idea working. — Paul Kruger, Aug 28 '18 at 09:47
Check out this answer too: https://stackoverflow.com/questions/43183450/jsdoc-typedef-in-a-separate-file — Sebastian Norr, Jun 24 '20 at 15:23

score 4 · Answer 1 · answered Aug 28 '18 at 12:58

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.
 */

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

how do you include the external file? – Purefan Oct 02 '20 at 21:50 — Purefan, Oct 02 '20 at 21:50

score 0 · Answer 2 · answered Sep 22 '22 at 15:20

This answer is mostly catered to VS Code if you're hoping to get Intellisense to pick up your types.

I've had success with simply creating my types in a typedefs.js file and referencing the type by using the ts/vscode import(path/to/file).Foo tag.

JSDoc does not support this syntax out of the box, so I suggest also using jsdoc-tsimport-plugin in order to parse your docs.

Eg: 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;
 }

Javascript: Move JSDoc's outside of code

2 Answers2

Linked