каким образом вы создаете документацию к API ? какими средствами?
буду рад ссылке на подобное обсуждение\голосовалку
возможные варианты:
1) пишу комменты к публичному API в формате доксигена, далее (делаю, есть возможность и тд) создаем в формате html, pdf, doc документацию с помощью doxygen.exe
2) пишу комментарий в произвольном формате в коде. для документации использую отдельные ресурсы типа wiki, doc, jira, etc, сижу там клепаю красивую документацию с диаграммами, болдами, курсивами и тд
зы: не знаю в какой форум лучше запостить это обращение, но C++ первичен
Здравствуйте, Аноним, Вы писали:
А>Расскажите, в чем суть комментирования в коде? Он же засирается до невозможности, вроде функции на 5 строчек и описания в хтмл-формате на 50.
Здравствуйте, Abyx, Вы писали:
А>>Расскажите, в чем суть комментирования в коде? Он же засирается до невозможности, вроде функции на 5 строчек и описания в хтмл-формате на 50. A>ИДЕ должна уметь сворачивать документацию
По мне так бесполезная фича.
[In theory there is no difference between theory and practice. In
practice there is.]
[Даю очевидные ответы на риторические вопросы]
Здравствуйте, uzhas, Вы писали:
U>каким образом вы создаете документацию к API ? какими средствами? U>буду рад ссылке на подобное обсуждение\голосовалку U>возможные варианты: U>1) пишу комменты к публичному API в формате доксигена, далее (делаю, есть возможность и тд) создаем в формате html, pdf, doc документацию с помощью doxygen.exe U>2) пишу комментарий в произвольном формате в коде. для документации использую отдельные ресурсы типа wiki, doc, jira, etc, сижу там клепаю красивую документацию с диаграммами, болдами, курсивами и тд
U>зы: не знаю в какой форум лучше запостить это обращение, но C++ первичен
Использую №1.
По догу службы учавствовал в одном проекте с полностью доксигеновской докой. Достаточно удобно, если подходить с умом.
Никто же не запрежает написать скрипты, чтобы генерировать разного рода диаграммы и затем вставлять их как картинки в конечный док. Да и сам доксиген позволяет встроить секвенс диаграммы и dot-диаграмма (используя внешние утилиты).
По поводу загажевания кода — никто не запрещает использовать для дока отдельные текстовые файл, в которых указывать элемент к которому относится комментарий — тут просто возникает неудобнство, что нужно отделать код от описания, что бывает сложно поддерживать при частом изменениии этого коска (переименование, переносы в другие неймспейсыф и прочее — т.е. то что влияет на полное име описываемго элемента).
Здравствуйте, uzhas, Вы писали:
U>каким образом вы создаете документацию к API ? какими средствами?
По долгу службы использую нечто между 1-м вариантом и ничем. Т.е. коменты пишутся чтобы были, документация генерится doxygen'ом. Комментировать результат, думаю, не стоит — и так все понятно.
Дома, для своих проектов, настроен маленький хоум-сервер. Svn + mantis + wiki. Так вот — сначала пишу в wiki, что я хочу сделать, архитектурное решение с детальным описанием насколько это возможно. Если требуется добавляю "картинки", разбавляю огрызками кода, которые найдены во время изучения "проблемы" и могут понадобится в качестве примера "как надо делать" или "как не надо делать". По мере написания, правлю статью, добавляю описание отдельных, более узких/частных моментов и наоборот более общих — от самых "верхних" интерфейсов до отдельных методов и свойств мелких вспомогательных классов, меняю первоначальную модель по мере изменяющихся требований (вернее по мере появления не замеченных сразу моментов, нюансов), ну и т.д... Все это перемешивается перекрестными ссылками на ревизии СВН и короткие заметки по реализации фич/исправлению багов в Мантис. В итоге, помимо зачастую бестолковых комментариев к методам, выстраивается достаточно четкое описание того, что сделано, зачем и почему так, а не иначе, описана архитектура, процесс формирования/жизни проекта. Получается очень удобно. Субъективно, но мне думается, что с такой документацией будет не сложно быстро разобраться в любом проекте человеку со стороны. А уж в своем коде с этими напоминалками — вообще красота.
Минусы
1) Время... хотя на раздумье его все равно тратить, а на бумаге (ну т.е. на экране) мысли, кажется, еще и быстрее выстраиваются (опять таки субъективно), если привыкнуть.
2) Приходится совмещать http-ссылки в коде с коментариями. Мелкие заметки по коду (вроде описания локальной переменной, когда их много) тащить в wiki нет смысла, да и неудобно это. А описание методов/интерфейсов/логики и т.д. написанные в wiki должно отражаться ссылкой в коде. Вот приходиться выбирать между "надо подробно"/"почти не надо".
3) Если для себя — будет работать. Если попросить кого то так писать, то вряд ли — получатся те же бестолковые заметки "чтобы было" и ни строчки "о главном" — лучше пускай пишет в исходниках на метод SetUserCount комментарий "Set user count".
Здравствуйте, uzhas, Вы писали:
U>возможные варианты: U>1) пишу комменты к публичному API в формате доксигена, далее (делаю, есть возможность и тд) создаем в формате html, pdf, doc документацию с помощью doxygen.exe
Только этот способ. Отделение документации от кода гарантирует несоответствие первой последнему. Закон Мерфи.
Да и удобно. В доксиген можно еще и диаграммы включать, которые тоже генерируются из комментариев при помощи того же plantuml.
Здравствуйте, Poirot, Вы писали:
P>По поводу загажевания кода — никто не запрещает использовать для дока отдельные текстовые файл, в которых указывать элемент к которому относится комментарий — тут просто возникает неудобнство, что нужно отделать код от описания, что бывает сложно поддерживать при частом изменениии этого коска (переименование, переносы в другие неймспейсыф и прочее — т.е. то что влияет на полное име описываемго элемента).
По поводу загаживания кода — это отмазы тех, кто ленится писать документацию.
Здравствуйте, los puercos, Вы писали:
LP>По поводу загаживания кода — это отмазы тех, кто ленится писать документацию.
а мне и отмазы не нужны, чтобы лениться писать документацию
