Autocomplete in React using JSDoc

This content originally appeared on JavaScript January and was authored by Emily Freeman

Many thanks to JavaScript Joe for this article!

One of my favorite reasons to use TypeScript with React is the autocomplete with which it gives you. It allows me to write code faster and provides a better code-writing experience! The only problem? Not everyone likes TypeScript and not every React project uses TypeScript. So how can we get this editor experience without TypeScript? The answer: JSDoc!

What is JSDoc?

If you haven't heard of JSDoc before, it is a standard for documenting your JavaScript code. Here's what it looks like:

/** This is a description of the sayHello function. */
function sayHello(name) {
  return `Hello, ${name}!`
}

Using special syntax, your editor can understand your JavaScript code. It can then provide things like tooltip documentation or autocompletion. The benefits are priceless. Not only does it make your code more readable, but it makes you code-writing experience more enjoyable!

How does it work?

JSDoc works is by adding a "JSDoc block" before your code along with special tags to signifiy different things. Let's expand upon our previous example:

    /**
     * @param  name - the name of the person you are saying hello to
     * @returns  a happy sentence saying hello to the person
     */
    function sayHello(name) {
      return `Hello, ${name}!`
    }

Here, we use two block tags: @param and @returns. In the first one, we state name is a parameter, or param, of type string and then add a short description. The second block tag tells us that the function returns a value of type string. Now, when we use this function in a separate module, we can see all this documentation in the tooltip. Here's what it looks like in VSCode:

Pretty cool, huh?

Do all editors support JSDoc?

Most major editors and IDEs support JSDoc including:

• VSCode
• WebStorm
• Atom
• IntelliJ
• Sublime via DoxyDoxygen

Using JSDoc with React

Now that we understand JSDoc and how it works, let's see how we can achieve autocomplete in React. Start by creating a basic React app using:

    npx create-react-app js-jan-app

Create a new file for our component called Button.jsx

    touch Button.jsx

Import React and set up a basic component:

    import React from 'react'
    
    export const Button = ({ textColor, bgColor }) => (
      <button
        style={{
          color: textColor,
          backgroundColor: bgColor
        }}
      >
        {children}
      </button>
    )

Now time to add our JSDoc block:

    import React from 'react'
    
    /**
    * Renders a <Button /> component
    * @param  props
    * @param  props.textColor - the color of the text in the button
    * @param  props.bgColor - the background color of the button
    * @param  props.overrideStyles - used to set the CSS of the button
    */
    export const Button = ({ textColor, bgColor, overrideStyles =  ) => (
      <button
        style={{
          color: textColor,
          backgroundColor: bgColor
          ...overrideStyles
        }}
      >
        {children}
      </button>
    )

We use the props object as our param and then elaborate on the props object keys like textColor and bgColor. By doing this, editors like VSCode can provide features like autocomplete.

Here's what this looks like:

That's it!

As you can see, the barrier to add this to your code is low but the gains are high. Documenting all your components like this will make future developers on the project happy. And more productive. Win-win for all!

---

If you'd like to go further, check out the official JSDoc documenation. There are over 50 block tags! Practice adding JSDoc blocks to your code. Experiment with new block tags. Try using ones you're unfamiliar with. The more you know, the better your code annotations will be.

Thank you for reading! Happy JSDoc-ing!

5: https: data-preserve-html-node="true"//packagecontrol.io/packages/DocBlockr%202020%20(DoxyDoxygen%20powered

This content originally appeared on JavaScript January and was authored by Emily Freeman