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

问题描述

我是“适当地”记录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) @R_836_4045@ion 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来读取该功能的文档+空格以显示其参数。

VS代码悬停功能示例：

VS Code ctrl + shift + space示例：

可以看到我的文档都没有出现。：/

当我稍稍更改文档时，我接近预期的结果，但还差得很远。

    /**
     * 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) @R_836_4045@ion in the correct language.
     * @param options.config - Request Config
     * @param {boolean} options.config.promptToRetry - Should this request,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代码悬停功能示例：

VS Code ctrl + shift + space示例：

正如我们所见，“悬停”屏幕示例的外观与我想要的完全相同，但是“ ctrl + shift + place”屏幕未显示文档。

请注意：我正在努力改善自己和代码，对不起，我不知道这样一件琐碎的事，但是我一直在努力使它整日工作。

谢谢您的帮助。

解决方法

使用标签@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 jsdoc