DEV Community

Devin W. Leaman
Devin W. Leaman

Posted on

Using Custom Types in JavaScript Docs

Hey dev community,

I come to you again with another question, this one less polarizing as my last one regarding gifs 😅 What I'm curious about is how you handle referencing custom types when writing method documentation in JavaScript with Visual Studio Code.

I'm sure that's not the best way of describing it, so I'll show what I mean instead. Take the following example:

// Used for JSDocs
const Window = require('vscode').window

/**
 * @typedef {Object} MessageOptions
 * @property {boolean} modal Indicates that this message should be modal.
 */

/**
 *
 * @param {Window} window
 * @param {string} text
 * @param {MessageOptions} [options]
 * @param {*[]} [items]
 */
module.exports.showMessage = (window, text, options = false, items = false) => {
  if (options && items) return window.showInformationMessage(text, options, items)
  else if (items) return window.showInformationMessage(text, items)
  else return window.showInformationMessage(text)
}

Enter fullscreen mode Exit fullscreen mode

It's a file I've created in order to help with my new project, Enmeti. For the one method it exports, I have two parameters that are custom, MessageOptions and Window.

For Window, the vscode module exports a window namespace so I can reference it as a variable and then use that in the comments. MessageOptions, on the other hand, isn't exported, so I created a custom definition and reference that.

While I'm fine with the definition for MessageOptions, I'm not too fond of creating a variable reference for Window just for the sake of having the parameter info available when referencing the method. This is something I've done in a number of my projects but I know there has to be a better way of doing this.

Any suggestions?

Discussion (12)

Collapse
thecyberronin profile image
Ronin • Edited on

If you don't want to go full Typescript, you can look into a typings file. I recently had an issue on an API wrapper that's dynamically created where someone didn't get any of the benefits of VSC's intellisense. This happened because the functions are dynamically created, so VSC can't get the info to properly use intellisense. I added a typings file, pushed to npm and the dev that created the issue was pleased. :)

I think Typescript is something that would be nice to use, but not always practical for usage from other developers depending on their skill level. Using a typings file can help without having to fully convert to Typescript.

Collapse
avalander profile image
Avalander

Unfortunately, typings files don't work for the project they are in, only if you import the package in another project. Since the OP's project seems to be a VS Code extension, I'm not sure how much it would benefit from having typings files.

Collapse
4lch4 profile image
Devin W. Leaman Author

This particular project is an extension but I'm also wanting to learn how to solve this going forward for any other Node modules I publish or create for private use.

Collapse
4lch4 profile image
Devin W. Leaman Author

Would you happen to have an example of what you mean? Or some resources to learn more about this?

Collapse
thecyberronin profile image
Ronin • Edited on

Unfortunately, you'll still have to get comfortable with TypeScript in order to use typings at its fullest. I think it may actually be a nice segway into learning TypeScript in my opinion. Starting out initially doing typings files would be a very good way to learn and get better with TypeScript. Since you'd be learning, starting out with a basic typings file would be a really good start.

I can give you the example that I shared with my initial comment. I created a lib that dynamically creates functions based on a JSON file with keys linking to API routes. A friend of mine asked me to create a wrapper for his API, with the intention of putting it on NPM.

I created the module and pushed to NPM, only recently I had an issue posted on the repo saying that a user couldn't get any intellisense to show when using it in VSC. I immediately knew that VSC had nothing to base it off of and VSC couldn't generate anything itself without the right information.

The module is nekos.life. A lot of the endpoints are NSFW, but like I said it's just a wrapper for my friend's API. If you take a look at the repo, you'll see that there is a typings folder containing the type file. You can also take a look at main file (index.js) to see what I mean when I say that VSC has nothing to base the intellisense off of without the type file. When you install the lib, VSC will grab the typings file and use it for intellisense. As you can see, the lib itself has no reference to any of the functions. The typings file is the MVP here. You can download the lib and see for yourself if you'd like and see the intellisense rendered from the typings file.

After taking a look at VSC's documentation, there are different ways to get the typings files. VSC will first look to see if they are contained in your package, after that there is a repo called DefinitelyTyped that it is then able to retrieve from if you don't have any typings files in the lib/package you are downloading.

Some links I got the information from:

Clarification on my comment about not having to go full TypeScript:
You are still using TypeScript, but you don't have to fool around with tsc or any config files to create a typings file to use with JS.
Also, if anything I said here was incorrect please let me know :)

Collapse
genejams profile image
{Gene}

I don't use VS Code (yet) but perhaps this can fit your needs:

medium.com/front-end-hacking/inclu...

I still recommend using jsDoc to document your code, so you'll have to mantain the .d.ts file separately.

For one of my projects I use a script that build the d.ts file out of the jsDoc comments. But it would be adding more complexity. Probably not worth it in your case.

Collapse
anurbol profile image
Nurbol Alpysbayev

One word: Typescript

Collapse
4lch4 profile image
Devin W. Leaman Author

I've thought of using TypeScript for a while but am not too fond of having to learn a new language just for better intellisense/type information.

Is there a good resource you'd recommend to learn more about how to use it?

Collapse
anurbol profile image
Nurbol Alpysbayev • Edited on

The beauty of Typescript is that it is designed with the "any Javascript is a Typescript" principle in mind. This means, that you can learn it gradually. You can simply rename an extension of your file from .js to .ts and add a first type you need. e.g.:

myJsFunction(youAlwaysForgetTheExactTypeOfThisArgument: number) {
  ...
}

And this was how I learned it: needed to describe a type, just tried to select a correct type intuitively first. If no success, then go to
typescriptlang.org/docs/home.html
typescriptlang.org/docs/handbook/b...
And of course, google, which in 95% cases directs you to the links listed above or to stackoverflow or sometimes:
basarat.gitbooks.io/typescript/con...

Collapse
kepta profile image
Kushan Joshi

Yes please use Typescript, instead of trying to hack around informal types with JSDoc.

Collapse
4lch4 profile image
Devin W. Leaman Author

Do you have any recommendations to learn TypeScript? I mentioned it above but I'm not too fond of having to learn a new language just for types info but if it's as helpful as it seems I may as well.

Collapse
kepta profile image
Kushan Joshi

As everyone said, typescript is a superset of JavaScript. So any valid JavaScript is already typescript, you add the types superpower at your leisure.