Создавать документацию JavaScript непосредственно из исходного кода

Я ищу инструмент для создания документации для функций и свойств JavaScript, даже если нет надлежащим образом отформатированных блоков комментариев, связанных с этими функциями или свойствами (например, Doxygen).

В этом сравнении между JSDoc и некоторыми другими документами упоминается, что JSDoc может анализировать исходный код для создания документации, даже если нет блоков комментариев (что-то вроде Doxygen, as Я упомянул выше). Говорят, что все другие инструменты только анализируют блоки комментариев.

Я установил JSDoc 3.3.0-alpha4 из npm (в node) в соответствии с этой инструкцией, и я пытаюсь создать документацию для своего проекта. Насколько я вижу, JSDoc не создает никакой документации для функций или свойств, которые не имеют надлежащих комментариев с соответствующими флагами JSDoc.

Я знаю, что JSDoc прошел множество итераций, была ли эта функция удалена или я не использую правильные ключи? Я попытался проверить параметры командной строки, но не смог найти для этого никаких переключателей. Я просто использую его следующим образом:

./node_modules/.bin/jsdoc -r -l my_project --destination doc/

Я знаю, что есть другие инструменты, которые могут автоматически добавлять блок документации к коду, например. smartcomments, но это не совсем то, что я ищу. Может ли кто-нибудь пролить свет на это?

Ответ 1

Я использовал Yuidoc для моего проекта. Он не читает код, только теги Yuidoc, такие как @class, @module, @method и т.д., Завернуты в блок комментариев следующим образом:/** */ Вы можете использовать его как расширение NodeJs и генерировать api, просто введя в свою папку javascript с помощью Node cmd и выполнив команду:

yuidoc .

Это немного сложно в начале, если вы не знаете, как его использовать.

Например, если у вас есть тег yuidoc, например:

/**
 * @class Claculator
 * @method claculate
 * @param {Number} a
 * @param {Number} b
 * @return {Number}
 */
function calculate(a, b) {

}

/**
 * @class Graphics
 * @method drawGUI
 * @param {Number} x
 * @param {Number} y
 * @param {Number} z
 * @return {Number}
 */
function drawGUI(x, y, z) {

}

Все методы/свойства, следующие за тегом @class, станут частью класса Calculator после поколения. Поэтому, если у вас есть метод drawGUI() после вычисления (a, b) и он должен принадлежать другому классу, например Graphics, то вы должны отметить это также в другом теге @class, как в приведенном выше примере.

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