Самодокументация кодаДокументация - важная часть библиотек, которую очень лень писать. Поэтому важно уметь писать код так, чтобы он был самодокументируемым. Но с этим не справляется ни babel, ни webpack, ни eslint.
Они предлагают писать свои конфиги по простой схеме
module.exports = {...}
А что писать в этом объекте? Ну, сам догадаешься, если мы забыли описать это в документации.
Но у нас есть jsdoc, с помощью которого мы можем связывать js код и ts типы, к примеру
/**
* @type {import('webpack').Configuration}
*/
module.exports = {}
И благодаря этим аннотациям код становится внезапно самодокументируемым. Ты можешь писать комментарии к конкретным полям в объекте, ты можешь помечать их аннотацией
@deprecated, ты можешь делать что угодно. И любому программисту это понятно.
Если же у тебя TS, то надо вообще форсить людей с помощью тупых функций
type Config = {};
export const declareConfig(config: Config) {
return config;
}
И эта штука ещё лучше. Ты спокойно можешь менять реализацию этой функции, менять конфиги внутри, если это требуется. И все IDE будут сразу помогать всем пользователям, так как ты зафорсил использование этой функции у пользователей.
Из относительно хороших примеров: посмотрите как организована система плагинов у rollup. Они во всю используют этот механизм для подключения внешних плагинов. Ты не просто описываешь конфиг, а вызываешь типизированную функцию.