JSDoc — это язык разметки, используемый для описания кода Javascript. В эпоху до того, как комментарии Typescript были уникальным способом определения информации не только об использовании и описании,
, но и о типе информации.
JSDoc — это стандартизация этой практики добавления комментариев для описания и документирования вашего кода, это ответвление схемы Javadoc,
но специализированное для кода Javascript.
/**
* Renders a new component with props
*
* Used by external plugins
*
* @param {Object} options
* @param {String} options.action an action to execute
* @param {String} [options.errorMessage] an optional error message to show
* @return {Promise<string>} a string with the content
*/
static async renderComponent({ action, errorMessage }) {
return template({ action, errorMessage })
}Most of current code editor supports this syntax to read and display documentation about the code, go ahead and try it out.
Typescript into the game
The Typescript team took JSDoc and added supports for the type information. Is it possible to use a variation of the JSDoc annotation syntax to provide
information about the types you will use.
Let’s take the previous example but this time with type annotations
/**
* Renders a new component with props
*
* Used by external plugins
*
* @param {String} action an action to execute
* @param {String} [errorMessage="default message"] an optional error message to show (with default value)
* @return {Promise<string>} a string with the content
*/
static async renderComponent({ action, errorMessage }) {
return template({ action, errorMessage })
}Looks similar right? That’s why TS “hijacked” some of the JSDoc syntax and added new meaning, but the real power comes when you define new types.
/**
* Renders a new component with props
*
* Used by external plugins
*
* @typedef {Object} Props
* @property {String} action an action to execute
* @property {String} [errorMessage="default message"] an optional error message to show (with default value)
*
* @param {Props} prop
* @return {Promise<string>} a string with the content
*/
static async renderComponent(props) {
return template(props)
}In this case, the @typedef annotation was used to create a type named Props and then the @property annotation is there to declare each of the properties that belongs to that object type.
After that, you can use the new type inside the same file were it was defined (unless you export the declaration).
Результат предыдущего фрагмента такой же, как
type Props = {
action: string;
errorMessage?: string
}
static async renderComponents(props: Props): Promise<string> {
return template(props)
}Зачем использовать JSDoc вместо Typescript?
Как и все в технике (и в жизни) это зависит. Существует ряд возможных вариантов использования.
Один из возможных вариантов использования (и тот, который я рассматриваю чаще всего): вы пишете простые скрипты для узлов и вам нужна некоторая безопасность типов при написании кода. Так как узел не поддерживает Typescript из коробки (пока),
вам нужно выполнить некоторую настройку, чтобы добавить его, и, возможно, скрипт достаточно мал, и он не стоит усилий (и сборка время).
Другой вариант: вы можете захотеть запачкать руки безопасностью типов, но без полной фиксации или полной миграции вашего проекта вы можете добавить комментарии к этому JSDoc
и начать наслаждаться лучшей жизнью.
Или, может быть, у вас такое же мышление, как у команды webpack (большая кодовая база Javascript), они решили обеспечить безопасность типов, но без этапа компиляции.
Наконец, одна из веских причин для использования JSDoc — создание документации. Существуют пакеты, которые используют комментарии JSDoc для создания сайтов документации, которые можно легко развернуть.
Недостатки?
Хорошо, я убеждаю вас использовать аннотацию типов через JSDoc, есть ли недостатки у этого подхода. И ответ - да, есть. Если вы автор библиотеки, то этот подход не для вас.
Тип JSDoc имеет сильную поддержку TS, но еще не является частью Typescript, поддерживается не весь синтаксис Typescript.
