В одной из своих библиотек хотелось бы задокументировать некоторые части кода, которые не всем будут понятны в отношении предметной области, а только некоторые по следующей причине:
- основной код вполне самодокументируемый
- комментарием в одну строку не обойтись, и могут потребоваться какие-то не только текстовые описания
В первом случае можно ориентироваться по туториалу к библиотеке (если есть вопросы по предметной области), в остальном все и так должно быть ясно хотя бы для тех, кто умеет читать код.
Во втором уже посложнее. Нужно как-то отдельно комментировать код, чтобы не перенасыщать его лишним текстом, и как уже было сказано - могут быть не только текстовые описания. И писать это рядом с основной документацией к проекту не то, так как это будет больше полезно для contributor'ов, а не пользователей.
Есть ли какие-то инструменты для написания комментариев к коду отдельно от него, но с проверкой целостности? Чтобы подсказывало что нового появилось в коде и предлагало его прокомментировать, и контролировало изменения
P.S. Если кто-то хочет возразить по поводу самодокументируемого кода, то
вот обратный пример
Особенно интересна строка:
var Tag = function(id, description, min, max, plc) {
Какой смысл тратить время на написание подобных комментов? Разве что тип указать, но в моем случае для этого есть
transform-flow-strip-typesдля
Babel@param {String} id - The ID of the Tag.
Трата времени, если и так ясно из кода что первый параметр это идентификатор для создания метки
