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)
}
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?
Top comments (11)
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.
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.
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.
Would you happen to have an example of what you mean? Or some resources to learn more about this?
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
typingsfolder 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
tscor any config files to create a typings file to use with JS.Also, if anything I said here was incorrect please let me know :)
One word: Typescript
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?
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.:
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...
Yes please use Typescript, instead of trying to hack around informal types with JSDoc.
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.
As everyone said, typescript is a superset of JavaScript. So any valid JavaScript is already typescript, you add the types superpower at your leisure.