Блог

Я новичок в «правильном» документировании исходного кода JavaScript, и я пытался задокументировать функцию, которая принимает параметр options (шаблон Options).

     /**
     * 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, я разочарован тем, что Intellisense от VS Code «неправильно» отображает документацию функции, когда разработчик пытается использовать этот метод.

Я создаю внешнюю документацию с использованием JSDoc, которая работает должным образом, однако, поскольку мы, разработчики, ленивые создания, я хочу, чтобы другие разработчики могли использовать функции VS Codes для чтения документации функции, либо наведя курсор на функцию, либо нажав ctrl shift пробел, чтобы показать ее параметры.

Пример функции наведения курсора 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» документация не отображается.

Пожалуйста, обратите внимание: я пытаюсь улучшить себя и свой код, мне жаль, что я не знаю такой тривиальной вещи, но я пытался заставить это работать целый день.

Спасибо за любую помощь.

Объявляйте типы с помощью тегов @typedef и @property .

Вы можете поместить @typedef блоки комментариев в любое удобное для вас место в файле.

После ввода с определениями типов VS Code поймет ваши типы и предоставит вам автозаполнение.

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

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

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