Я склоняюсь к другой мысли: использовать тот же JSDoc, с темплейтом haruki, который экспортирует доки в JSON. Файл publish.js достаточно прост, чтоб его модифицировать и реализовать кастомные теги. После экспорта в JSON, скормить его самописному шаблонизатору-генератору страниц. Сами доки вынести в отдельный JS файл.
/**
@lang en
@function f
@summary cool function
@desc description
@param {integer} x - my X
@param {string} [y] - my Y
*/
Такое решение решит несколько проблем:
- Удобный и неизбыточный синтаксис остаётся, не нужно мудрить с XML и другими форматами описания данных.
- Уйдет бардак в коде. Больше половины кода сейчас занимает документация. С новыми языками будет еще больше бардака.
- Файл с доками можно будет подключать отдельно в IDE, так как, в основном, либа будет использоваться в минифицированном виде. Причем, можно будет подключить доки на любом языке, а написать новую локализацию не составит труда: копируй файл и переводи.
Нерешенные проблемы:
- Нужно постоянно следить за соответствием документаций: поменялся аргумент или пример, нужно изменить доки ко всем языкам.
- Не понятно, в каком месте (в каком файле и строке) описан метод. Со старым способом в сгенерированной HTML документации всегда было понятно, где найти реализацию метода. Возможно, для решения этой проблемы есть какой-то тег.
- Не работают теги @link
- Персер Харуки не обрабатывает определние типов