Как мне документировать Lua API / объектную модель, написанную на коде C ++?
Я работаю над документированием нового и расширенного Lua API для игры Bitfighter (http://bitfighter.org). Наша объектная модель Lua является подмножеством объектной модели C ++, а методы, предоставляемые Lua, которые мне нужно документировать, являются подмножеством методов, доступных в C ++. Я хочу документировать только те элементы, которые имеют отношение к Луа, а остальные игнорировать.
Например, объект BfObject является корнем всех объектов Lua, но сам находится в середине дерева объектов C ++. BfObject имеет около 40 методов C ++, из которых около 10 относятся к скриптам Lua. Я хочу, чтобы наша документация показывала BfObject в качестве корневого объекта и показывала только эти 10 соответствующих методов. Нам также необходимо показать дочерние объекты таким образом, чтобы было понятно наследование методов.
На данный момент мы можем предположить, что весь код написан на C ++.
Одна из идей заключается в том, чтобы как-то пометить объекты, которые мы хотим задокументировать, таким образом, чтобы система, такая как doxygen, знала, на что смотреть, и игнорировала все остальное. Другой способ заключается в предварительной обработке кода C ++ таким образом, чтобы удалить все не относящиеся к делу биты и документировать то, что осталось с чем-то вроде doxygen. (На самом деле я довольно далеко продвинулся в этом подходе с использованием luadoc, но не смог найти способ заставить luadoc показывать иерархию объектов.)
Одна вещь, которая может оказаться полезной, заключается в том, что каждый класс объектов Lua регистрируется согласованным образом вместе со своим родительским классом.
Существует все больше игр, использующих Lua для написания сценариев, и многие из них имеют приличную документацию. У кого-нибудь есть хорошее предложение о том, как его производить?
PS Чтобы уточнить, я счастлив использовать любой инструмент, который будет выполнять эту работу — doxygen и luadoc — это лишь примеры, с которыми я немного знаком.
Решение
Я нашел решение, которое, хотя и не идеально, работает довольно хорошо. Я собрал воедино скрипт Perl, который просматривает весь исходный код Bitfighter и производит второй набор «поддельных» исходников, который содержит только те элементы, которые я хочу. Затем я могу запустить этот вторичный источник через Doxygen и получить результат, который составляет 95% от того, что я ищу.
Я объявляю победу.
Одним из преимуществ этого подхода является то, что я могу документировать код «естественным» способом, и мне не нужно беспокоиться о том, чтобы пометить, что входит, а что нет. Скрипт достаточно умен, чтобы понять это из структуры кода.
Если кому-то интересно, скрипт Perl доступен в исходном архиве Bitfighter по адресу https://code.google.com/p/bitfighter/source/browse/luadoc.pl. Он завершен только примерно на 80%, и в нем отсутствуют некоторые очень важные элементы (например, правильное отображение аргументов функций), но структура есть, и я удовлетворен тем, что процесс будет работать. Сценарий улучшится со временем.
(Очень предварительные) результаты процесса можно увидеть на http://bitfighter.org/luadocs/index.html. Шаблоны вряд ли были изменены, поэтому они выглядят очень «стандартно», но показывают, что все работает более или менее.
Поскольку некоторые комментаторы предположили, что с помощью Doxygen невозможно создать хорошую документацию, я должен отметить, что почти ни один из наших встроенных документов еще не добавлен. Чтобы понять, как они будут выглядеть, посмотрите класс Teleporter. Это не супер хорошо, но я думаю, что это опровергает мнение, что Doxygen всегда производит бесполезные документы.
В данный момент я сожалею о том, что мое решение действительно одноразовое и не учитывает растущую потребность сообщества. Возможно, в какой-то момент мы стандартизируем способ слияния C ++ и Lua, и задача создания обобщенного инструмента документации станет более управляемой.
PS Вы можете видеть, как выглядит разметка в исходных файлах … смотрите https://code.google.com/p/bitfighter/source/browse/zap/teleporter.cpp, и искать @luaclass
Другие решения
Исключите из пространства имен (также может быть классом) ваш код C ++, но не код lua
EXCLUDE_SYMBOLS = myhier_cpp::*
в конфигурационном файле doxygen или вишни выбрать что исключить с помощью
/// @cond
class aaa {
...
...
}
/// @endcond
в вашем коде c ++.
Я лично считаю, что разделение по пространству имен лучше, поскольку оно отражает разделение в коде и документации, что приводит к схеме на основе пространства имен для отделения чистого c ++ от привязок lua.
Разделение через исключение, вероятно, является наиболее целенаправленным подходом, но для этого потребуется дополнительный инструмент для анализа кода, разметки соответствующих частей lua и добавления исключения в код. (Кроме того, вы можете также отображать специальную информацию, такую как графики, отдельно с помощью этой разметки и добавлять их через изображение в документацию, по крайней мере, это легко сделать с помощью Doxygen.). Поскольку должна быть какая-то индикация кода lua, разметка, вероятно, не слишком сложна для получения.
Другое решение заключается в использовании LDOC. Это также позволяет вам писать комментарии на C ++, которые будут проанализированы LDoc и включены в документацию.
Преимущество состоит в том, что вы можете точно так же использовать инструмент для документирования кода lua. Недостатком является то, что проект, кажется, не поддерживается. Также может оказаться невозможным документировать сложные иерархии объектов, как упомянуто спрашивающим.
Я сам разобрал его для некоторых небольших корректировок, касающихся c ++. Посмотри Вот.