Documentation guide: best practices for indicating optional return values

Question

Documentation guide: best practices for indicating optional return values

I am tasked with properly documenting a function using JSDoc. The function triggers something if it returns true, otherwise it does not. However, the return value must always be of boolean type.

Here is my proposed JSDoc documentation:

* @return {boolean=false} Trigger for default event handler:
*
* Value | Description
*-------|-------------------------------
* true  | Disable default event handler
* false | Enable default event handler

Can you help me choose the correct solution? Thank you!

javascript documentation jsdoc

Answer 1

Answer №1

Here is a simple addition to the possible return values:

* @return {boolean} flag for default event handler:
*
* Possible values:
* Value | Description
*-------|-------------------------------
* true  | deactivates default event handler
* false | activates default event handler
*
* Return `false` or simply leave it blank if you want to keep the default event handler unchanged.

In my opinion, this solution is both straightforward and accurately represents the intended behavior.

Answer 2

Here is a simple addition to the possible return values:

* @return {boolean} flag for default event handler:
*
* Possible values:
* Value | Description
*-------|-------------------------------
* true  | deactivates default event handler
* false | activates default event handler
*
* Return `false` or simply leave it blank if you want to keep the default event handler unchanged.

In my opinion, this solution is both straightforward and accurately represents the intended behavior.

Documentation guide: best practices for indicating optional return values

Answer №1

Similar questions

Tips for retrieving the posted object in angularJS

Tips for activating a deactivated input field in ReactJS

What is preventing the click function on a dynamically created button from being executed in jQuery?

Exclude basic authentication for a specific route

Function executed prior to populating $scope array

Executing a for loop concurrently by utilizing async/await promises

Import a JSON file into Parse by reading and parsing it to store in the database

How can I switch the visibility of two A HREF elements by clicking on one of them?

When using the `coffee-util` library, an issue may arise if the `require('./module')` function ends

You can only use the angularjs http function once

Is it beneficial to use both Bootstrap and ng-bootstrap together?

What is the best method for combining ajax and php to perform a redirect?

Issue with Tanstack React Query failing to import

Is using .htaccess a reliable method for securing a specific file on the server?

The function history.popstate seems to be malfunctioning, as it is triggered by both the forward and backward navigation buttons in

Attempting to send a POST request, only to be informed by the form that it is devoid of

Encountering a 500 internal server error while accessing the web server

Error encountered during Next.js project build: Entry point specified for implicit type library 'build'

Utilizing Think ORM seamlessly across multiple files without the need to repeatedly establish a connection to the

Running shell commands through child_process in JavaScript