CODEWITHSUNDEEP
javascriptjsdoc
LostSoul
LostSoul

Reputation: 401

Documenting a functions options literal param - Javascript

I am new to "properly" documenting JavaScript source code and I have been trying to document a function that takes an options param (Options Pattern).

    /**
     * API request to retrieve a list of the availables routes/rallies.
     * 
     * @param {Object} options - Request Options
     * @param {Object} options.data - Request Data (Query Params)
     * @param {string} options.data.clientLanguage - The langauge of the client. Will be used by the API to return the route(s) information in the correct language.
     * @param {Object} options.config - Request Config
     * @param {boolean} options.config.promptToRetry - Should this request, upon failure, prompt the user to retry the request if the default error handlers are set.
     * @param {Object} options.callbacks - Request Callbacks
     * @param {function(RoutesResponse)} options.callbacks.success - Callback on success. Contains RoutesResponse.
     * @param {function(BusinessLogicError)} options.callbacks.businessLogicError - callback on business logic errors (api errors). Contains BusinessLogicError.
     * @param {function(HttpError)} [options.callbacks.httpError=BaseRepository.httpErrorHandler] - (Optional) callback on http errors (protocol errors). Contains HttpError. Leave undefined if a default HTTP handler should handle the error. Default: BaseRepository.httpErrorHandler.
     * @param {function()} [options.callbacks.timeOut=BaseRepository.timeOutHandler] - (Optional) callback on request timeout. Leave undefined if a default Timeout handler should handle the timeout. Default: BaseRepository.timeOutHandler.
     */
    this.getRoutes = function( options ) {
        ...
    }

Given my non exisiting experiance with documenting JavaScript functions I am frustrated that VS Code's Intellisense does not "correctly" display the function's documentation when a developer tries to use this method.

I am creating an external documentation using jsDoc, which works as expected, however since we developers are lazy creatues I want that other developers can use VS Codes features to read the function's documentation by either hovering of the function or pressing ctrl+shift+space to show its paramters.

VS Code hover function example:

enter image description here

VS Code ctrl+shift+space example:

enter image description here

As one can see none of my documentation is showing up. :/

When I slightly change the documentation, I get close to my expected result but not quite yet.

    /**
     * API request to retrieve a list of the availables routes/rallies.
     * 
     * @param options - Request Options
     * @param options.data - Request Data (Query Params)
     * @param {string} options.data.clientLanguage - The langauge of the client. Will be used by the API to return the route(s) information in the correct language.
     * @param options.config - Request Config
     * @param {boolean} options.config.promptToRetry - Should this request, upon failure, prompt the user to retry the request if the default error handlers are set.
     * @param options.callbacks - Request Callbacks
     * @param {function(RoutesResponse)} options.callbacks.success - Callback on success. Contains RoutesResponse.
     * @param {function(BusinessLogicError)} options.callbacks.businessLogicError - callback on business logic errors (api errors). Contains BusinessLogicError.
     * @param {function(HttpError)} [options.callbacks.httpError=BaseRepository.httpErrorHandler] - (Optional) callback on http errors (protocol errors). Contains HttpError. Leave undefined if a default HTTP handler should handle the error. Default: BaseRepository.httpErrorHandler.
     * @param {function()} [options.callbacks.timeOut=BaseRepository.timeOutHandler] - (Optional) callback on request timeout. Leave undefined if a default Timeout handler should handle the timeout. Default: BaseRepository.timeOutHandler.
     */
    this.getRoutes = function( options ) {
        ...
    }

Note, I removed the {Object} types from the doc.

Now VS Code kind of does what I want.

VS Code hover function example:

enter image description here

VS Code ctrl+shift+space example:

enter image description here

As one can see the "hover" screen example looks exactly as I want it, but the "ctrl+shift+place" screen does not show the documentation.

Please note: I am trying to better my self and my code, I am sorry that I do not know such a trivial thing, but I have been trying to get this to work the whole day.

Thank you for any help.

Upvotes: 2

Views: 322

Answers (1)

dwmorrin
dwmorrin

Reputation: 2744

Declare types using the tags @typedef and @property.

You can put the @typedef comment blocks anywhere you like in the file.

Once typed with the type definitions, VS Code will understand your types and give you autocompletion.

/**
 * @typedef {Object} RequestOptions
 * @property {RequestData} data
 * ...
 */

/**
 * @typedef {Object} RequestData
 * @property {string} clientLanguage
 * ... 
 */

/** @param {RequestOptions} options */
this.getRoutes = function( options ) {
  // ...
}

Upvotes: 1

Related Questions