Создавать документацию 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, как в приведенном выше примере.
Примечание. С моей точки зрения, создание блоков комментариев помогает улучшить качество кода при разработке, а также помогает находить проблемы еще до того, как они произойдут.
