Существует ли "wiki” для редактирования комментариев doxygen?[закрыто]

Question

Я работаю над довольно большим игровым движком RTS с открытым исходным кодом (Весна).Недавно я добавил кучу новых функций C ++, вызываемых Lua, и мне интересно, как наилучшим образом их документировать и в то же время стимулировать людей к написанию / обновлению документации для очень много из существующих вызовов Lua.

Поэтому я подумал, что было бы неплохо, если бы я мог изначально написать документацию в виде комментариев doxygen рядом с функциями C ++ - это легко, потому что тело функции, очевидно, точно определяет, что делает функция.Тем не менее, я бы хотел, чтобы документация была улучшена разработчиками игр, использующими движок, которые обычно плохо понимают git (VCS, который мы используем) или C ++.

Следовательно, было бы идеально, если бы существовал способ автоматической генерации apidocs из файла C ++, а также иметь веб-интерфейс, подобный wiki, чтобы позволить гораздо более широкой аудитории обновлять комментарии, добавлять примеры и т.д.

Итак, мне интересно, существует ли веб-инструмент, который объединяет форматирование в стиле doxygen, редактирование этих комментариев в стиле wiki (предпочтительно без разрешения редактировать какие-либо другие части исходного файла) и git?(для фиксации комментариев, измененных через веб-интерфейс, в специальную ветку)

Затем мы, разработчики, могли бы время от времени объединять эту ветку, чтобы добавлять улучшения в главную ветку, и в то же время любые улучшения, вносимые разработчиками в документацию, попадали бы в этот веб-инструмент простым объединением главной ветки с этой специальной веткой.

Я пока ничего не нашел, сомневаюсь, что что-то подобное еще существует, так что любые предложения приветствуются!

Answer 1

Это действительно очень классная идея, и пару лет назад у меня тоже была очень острая потребность в чем-то подобном.К сожалению, по крайней мере тогда, я не смог найти что-то подобное.Быстрый поиск по sourceforge и freshmeat также не выдает ничего связанного с сегодняшним днем.

Но я согласен, что такой вики-интерфейс к документации, предоставленной пользователями, был бы очень полезен, я точно знаю, что нечто подобное недавно обсуждалось также в сообществе Lua (см. это).

Итак, может быть, мы сможем определить требования, чтобы создать базовый рабочий проект / прототип?

Надеюсь, это побудило бы нас инициировать такой проект с минимальным набором функций, а затем просто выпустить его на волю как проект с открытым исходным кодом (напримерна sourceforge), чтобы другие пользователи могли внести в него свой вклад.

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

Возможно, можно было бы реализовать что-то подобное, модифицировав существующее (устоявшееся) программное обеспечение для вики, такое как mediawiki.Или, предпочтительно, что-то, что уже использует git в качестве серверной части для целей хранения.Тогда в основном нужно было бы учитывать эти комментарии в стиле Doxygen и предоставлять простой интерфейс поверх этого.

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

Вероятно, это в основном сводилось бы к предоставлению автономного скрипта с doxygen (напримерна python, php или perl), а затем при необходимости встраивать формы в автоматически созданную HTML-документацию, чтобы исправления / дополнения документации можно было отправлять соответствующему скрипту через браузер, который, в свою очередь, записывал бы любые изменения обратно в соответствующую ветку.

В долгосрочной перспективе было бы здорово, если бы такой скрипт поддерживал различные типы бэкэндов (CVS, SVN или git) или, по крайней мере, был реализован достаточно обобщенно, чтобы его можно было легко расширять.

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

Даже если идея напрямую не материализуется в реальный проект, было бы интересно посмотреть, скольким другим пользователям на самом деле нравится эта идея, чтобы о ней можно было упомянуть в doxygen issue tracker (https://github.com/doxygen/doxygen/issues/new).

Редактировать:Возможно, вы также захотите ознакомиться это статья под названием "Документация, Git и MediaWiki".