Вжух и готово — генерируем документацию из TypeScript кода с Typedoc

[knotri]

   * @param key Key to identify value in container.
   * @param value Value to inject.
   * @returns Created or existing [DiRecord]{@link DiRecord}
 public register<KeyT, ValueT>(key: KeyT, value: ValueT): Typedin.DiRecord<KeyT, ValueT>

То есть вы просто продублировали информацию о типах из тайпскрипта еще раз???
Это отвратительно. Я уже вижу ситуацию когда параметр функции кто-то перепишет — а документация останется без изменений.

[PFight77]

Это Вы о returns? Там да, пожалуй упоминание типа лишнее. В целом, информацию о типе typedoc берет из кода, дублировать ничего не нужно.

[shyr1punk]

Пользуетесь линтингом JSDoc комментариев? Конкретно интересуют правила, которые позволяют избегать дублирования конструкций языка: типов, модификаторов доступа и т.д.

[PFight77]

Не очень понял, что там можно линтить. Поясните, пожалуйста.

[shyr1punk]

Чтобы линтер ругался в случае, который описал knotri в первом комментарии. Когда в JSDoc указан тип, например — это избыточно и может породжать ошибки в дальнейшем.

[PFight77]

Можно, наверное, попробовать сделать плагин для typedoc.

[plastilinko]

Да вот с этими средствами автогенерации документации все весьма сложно нынче. По работе требовалось распарсить сложный контейнер из js+php+sql и в итоге остановились на весьма старом мамонте под названием robodoc, часть функционала докрутил руками прямо в исходниках на C, с остальными вариантами на в роде jsdoc или sphinx подружиться не получилось по причине того что они пытаются распарсить весь контейнер под видом одного ЯП, есть еще DITA но там с первого подхода вообще черт ногу сломит.

[SaitoNakamura]

Честно говоря зайдя на сайт не очень понял реальную пользу от такой доки, она выглядит как типичные части MSDN, где про метод GetSepulkiFromSepulkary(int id) будет сказано что он достает сепульки из сепулькария и принимает целочисленный id в качестве параметра. Эти доки полезны в качестве тайпингов прямо в IDE, где ты получишь автодополнение или просто просмотр сигнатур, но не на сайте. На сайте гораздо полезней были бы реальные примеры использования (то что пытался делать Stackoverflow Documentation, хотя сам этот проект провалился), взаимодействия между методами, подводные камни и т.п. А сейчас я захожу и вижу



Куда мне здесь пойти и как этим пользоваться я не очень понимаю.

[mayorovp]

Это разные типы документации. И все они нужны.

[PFight77]

Есть еще отдельная документация, это чисто справочник по API. В .NET тоже всю документацию можно посмотреть в IDE, и тем не менее часто удобно зайти на MSDN и посмотреть описание конкретного класса. Здесь подразумевается, что ты уже знаешь название класса, например, и нужно просто посмотреть его API. Ну и разумеется, все это в IDE тоже доступно.

Конечно, хочется сделать структурированное содержание, чтобы все было не таким вот сплошным списком, а в виде дерева. Например, в соответствии со структурой директорий в исходниках. Но из коробки такое не поддерживается, а сделать пока руки не доходят.