Всем привет.
Решил документировать свой код, но столкнулся с рядом проблем. В первую очередь у меня возникли вопросы с описанием объектов. Затем, когда я попытался сгенерировать тестовую документацию, у меня ничего не получилось. Поэтому, вопрос, для начала, касается генераторов.
Сразу скажу, что, хотя я и ношу звание программиста, у меня довольно часто возникают проблемы с установкой и использованием чего-либо нового. В качестве образовательной машины приобрел Raspberry PI, дабы перестать бояться командной строки, научиться устанавливать и настраивать серверные штуки, запустить синхронизацию рабочих проектов.
Зайдя на эту страницу
https://github.com/jsdoc3/jsdoc я выяснил, что мне, для начала, надо поставить
https://github.com/hegemonic/rhino но там, к моему сожалению, не оказалось ни единого намёка на инструкцию по установке. Эту идею я оставил на потом, продолжив поиск альтернативного генератора.
Вторым кандидатом на генератор документации я выбрал
http://www.seehuhn.de/pages/jvjsdoc . Проблем с установкой и запуском небыло (какие проблемы, если нужно всего лишь клонировать репозиторий и запустить файлик). Но меня разочаровало то, что я не смог найти возможности указать в качестве источника конкретные файлы, а не целую папку. Кстати, скрипт лез и в недокументированные места и попытался как-то криво сгенерировать доку и для них.
Третьим кандидатом был yuidocjs. Устанавливая его с помощью npm, получил кучу ошибок.
О том, что у меня руки из жопы растут, прошу на писать
В общем, первый вопрос: как сгенерировать документацию для конкретных файлов?
После этого, хотелось бы получить ответы на ряд вопросов самого процесса документирования (например, как описать объект, в котором, под произвольными ключами, лежат объекты одной структуры).
Спасибо.