Velo: Using JSDoc

The Code editor supports JSDoc, a popular markup language used to document JavaScript code. The Code editor uses JSDoc to generate type checking and code autocomplete. Adding this annotation to your custom code allows you to benefit from these features. This can help you keep your code error-free throughout your site and is especially useful in large or complex projects.

Adding JSDoc to Velo Code

You can add JSDoc to Velo code as you would to any JavaScript code, by including the annotations just above the code you are documenting.

For example, consider the following function:

1
export function salaryCalculator (employee) {
2
   return `Salary for ${employee.name}: ${employee.jobPercentage * employee.seniority * 100}`;
3
}

Because this is a custom function, the Code Editor doesn’t know what properties to expect for the employee parameter. To fix this, we can add JSDoc annotation:

1
/**
2
* @typedef {object} employee
3
* @property {string} name Employee's name.
4
* @property {number} seniority The number of years the employee has worked at the   company.
5
* @property {number} hours The number of hours the employee works a week.
6
*
7
* @param {employee} employee
8
*/
9
export function salaryCalculator (employee) {
10
   return `Salary for ${employee.name}: ${employee.hours * employee.seniority * 100}`;
11
}

Autocomplete is now enabled:

The Code editor now also performs type checking on arguments passed into this function:

These features are now available for this function across the site, wherever we import this code.

Importing JSDoc from Other Code Files

The Code editor allows you to define JSDoc types in one file, and use them throughout your site. This is useful if you use custom objects in multiple places in your code. To do this, create a new .js file on your site and add your JSDoc definitions to it using the @typedef tag. To import these definitions in other files, use one of the following methods:

1. Global scope
   If you want your custom definitions to be available in every file on your site, leave your JSDoc definitions file as it is. Unless your file includes an export statement, the Code editor treats its definitions as global. This means you can use them anywhere on your site without an import statement.

2. Restricted scope
   To use your custom definitions in some files but not others, add export{}; after the last line of your definitions file. This tells the Code editor to treat your definitions as a module. Import the definitions into other files using the following syntax in your JSDoc code:
   {import('backend/myDefinitionsFile.js').myTypedefName}

   For example, to add a reusable JSDoc definition for an employee object to a site, we take the following steps:

   1. Create a new backend code file for the definitions. We’ll call it jsdoc-defs.js.

   2. We add the following code to the file:

      Copy

      1
      /**
      2
       * @typedef {object} employee
      3
      * @property {string} name Employee's name.
      4
      * @property {string} seniority The number os years the employee has worked at the company.
      5
      * @property {number} hours The number of hours the employee works a week.
      6
      */
      7
      export {};

   3. We can now import the definition whenever needed. In this case, we use it to define a parameter for a function:

      Copy

      1
      /** @param {import {'backend/jsdocs-defs.js'}.employee} employee */

When to Add JSDoc

Here are some cases where adding JSDoc to your code can improve your coding experience:

Custom code

Use JSDoc to enable autocomplete and type checking for your site’s custom code.

Velo packages

Adding JSDoc to the code in your Velo packages allows anyone using your package to receive autocomplete and type checking prompts.

Backend event handlers (Wix Editor)

The file for backend event handlers, events.js, doesn’t support autocomplete and type checking by default. You can add this functionality by adding JSDoc to event handler functions using the following syntax:

/** @param {import('api-module-name').Events.EventObjectName} parameterName */

For example:

To add JSDoc annotation to a Wix Bookings onBookingCanceled event handler, take the following steps:

1. Open the API reference for the event handler and locate the event object name. In this case, it’s BookingEvent.

   

2. Add the following JSDoc annotation above the event handler function in the events.js file:

   Copy

   1
   /** @param {import ('wix-bookings-backend').Events.BookingEvent}bookingEvent */

Autocomplete is now enabled.

Router functions (Wix Editor)

By default, the routers.js file doesn’t support autocomplete or type checking for WixRouterRequest objects passed to router functions. You can add this functionality by adding the following JSDoc annotation above your router functions:

/** @param {import('wix-router').WixRouterRequest} parameterName */

Working with editor elements in public code files (Wix Editor)

Sometimes, you may have code in public files that you use on several site pages. If you work with editor elements in this code, you may notice that there is no autocomplete or type checking. Adding JSDoc annotation to the code in your public files enables these features both there and when importing into page code.

For example, consider the following function in a public code file:

1
export function verifyText(textElement) {
2
    textElement.text += ' Verified';
3

4
    return textElement;
5
)

This function modifies an editor text element object. Because there is no JSDoc annotation, when we import this code into page code, the Code editor can’t confirm that we are passing the right values into the function. To fix this, we can add the following JSDoc annotation to the function:

1
/** @param ($w.Text) textElement */

Note that all $w element types are available for use in JSDoc in Velo code files.

Once we add the JSDoc, autocomplete and type checking are enabled: