IN THIS ARTICLE

Velo: Using JSDoc

The Velo 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:

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

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:

Copy Code
/**
* @typedef {object} employee
* @property {string} name Employee's name.
* @property {number} seniority The number of years the employee has worked at the   company.
* @property {number} hours The number of hours the employee works a week.
*
* @param {employee} employee
*/
export function salaryCalculator (employee) {
   return `Salary for ${employee.name}: ${employee.hours * employee.seniority * 100}`;
}

How does this code work?

JSDoc uses tags to define JavaScript code. The annotation we added above uses several of these tags to define the employee parameter for our function.

Each line of our annotation includes at least 3 components:

An ‘@’ character followed by the name of the tag
A data type surrounded by curly brackets
The name of the item being defined. This appears in plain text after the data type.

Some of the lines also include a description. This is also in plain text and is separated from the item’s name with a space. The descriptions appear in the Code Editor’s autocomplete display.

Let’s look at the annotations we added line by line:

@typedef {object} employee
The @typedef tag allows us to define a custom data type that can be used as a parameter or variable in other parts of the code. In this case we are defining an object and naming it employee.

**@property {string} name Employee's name.
**Once we use the typedef tag, JSDoc expects us to list the properties of the object we’re defining. To do this, we use the @property tag. This line defines a string property called name and adds “Employee’s name” as a description. The next 2 lines define 2 more properties of the employee object called seniority and hours.

**@param {employee} employee
**Now that we’ve defined the employee object, we need to tell JSDoc to expect it as a parameter for the salaryCalculator function. To do this, we use the @param tag. This line defines a parameter with the type employee and also names it employee. JSDoc applies the parameter definitions in a block of annotation to the function defined below the block. Note that even though this line is in the same block of code as the preceding lines, it’s not part of the type definition.The JSDoc site has more information about getting started, and has a list of the available tags.

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.

Note Autocomplete and type checking for code imported from web modules are not yet supported.

Importing JSDoc from Other Code Files

The Velo 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:

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

See an example

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

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

We add the following code to the file:

Copy Code
/**
 * @typedef {object} employee
 * @property {string} name Employee's name.
 * @property {string} seniority The number os years the employee has worked at the company.
 * @property {number} hours The number of hours the employee works a week.
 */
 export {};

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

Copy Code
/** @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
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 */
You can find the names of event objects in the Velo API reference.

See an example

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

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

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

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

Autocomplete is now enabled.

Router functions
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
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.

See an example

Consider the following function in a public code file:

Copy Code
export function verifyText(textElement) {
    textElement.text += ' Verified';

    return textElement;
)

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:

Copy Code
/** @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:

Was this helpful?

Yes