记录函数选项文字参数 - Javascript

Question

我是“正确”记录 JavaScript 源代码的新手，我一直在尝试记录一个采用选项参数（选项模式）的函数。

    /**
     * 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 ) {
        ...
    }

鉴于我没有记录 JavaScript 函数的经验，当开发人员尝试使用此方法时，VS Code 的 Intellisense 无法“正确”显示函数的文档，我感到很沮丧。

我正在使用 jsDoc 创建外部文档，它按预期工作，但是由于我们开发人员是懒惰的生物，我希望其他开发人员可以使用 VS Codes 功能通过悬停函数或按 ctrl 来阅读函数的文档+shift+space 显示其参数。

VS Code 悬停函数示例：

VS Code ctrl+shift+space 示例：

如您所见，我的文档 none 正在显示。 :/

当我稍微更改文档时，我接近了我的预期结果，但还不是很接近。

    /**
     * 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 ) {
        ...
    }

请注意，我从文档中删除了 {Object} 类型。

现在 VS Code 可以满足我的要求。

VS Code 悬停函数示例：

VS Code ctrl+shift+space 示例：

可以看出，“悬停”屏幕示例与我想要的完全一样，但“ctrl+shift+place”屏幕不显示文档。

请注意：我正在努力改善自己和我的代码，很抱歉我不知道这么琐碎的事情，但我一直在努力让它工作一整天。

感谢您的帮助。

Answer 1

使用标签 @typedef 和 @property.

声明类型

您可以将 @typedef 注释块放在文件中您喜欢的任何位置。

使用类型定义输入后，VS Code 将理解您的类型并为您提供自动完成功能。

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

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

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

记录函数选项文字参数 - Javascript

Documenting a functions options literal param - Javascript

javascript

jsdoc