记录函数选项文字参数 - 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+空格示例：

正如大家所见，我的文档都没有出现。 ：/

当我稍微更改文档时，我接近了我的预期结果，但还没有完全达到。

    /**
     * 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+空格示例：

正如我所见，“悬停”屏幕示例看起来与我想要的完全一样，但“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 ) {
  // ...
}