В сообществе Boost существует несколько стилей документирования. Большинство библиотек в настоящее время используют QuickBook, документацию в стиле WikiWiki.
Повышаю. Геометрия началась с Доксигена, и во время обзора было решено перейти на QuickBook. Тем не менее, было удобно держать доксиген и там: он хорошо сочетает описания с функциональными и классовыми декларациями.
Doxygen способен генерировать XML (помимо обычного вывода HTML), содержащий всю документацию.
Поэтому задача состояла в том, чтобы перевести XML, созданный доксигеном, в QuickBook. По крайней мере, переводить его части. В настоящее время Boost содержит два инструмента, использующих XSLT для перехода от Doxygen-XML к BoostBook или QuickBook. Эти инструменты используются в Boost. Случайно и быстро. Азио (и, возможно, больше). Однако этот процесс XSLT был довольно сложным, не дал желаемых результатов, и мы все программисты на C++. Так родился еще один инструмент, на этот раз на C++ с использованием RapidXML, от Doxygen-XML до QuickBook с возможностью смешивания обоих.
Процесс выглядит следующим образом:
- call Doxygen переходит от C++ к XML
- вызов doxygen_xml2qbk для перехода из XML в QuickBook
- вызов bjam из QuickBook в HTML
- bjam переводить Скачать QuickBook для BoostBook
- bjam переводится с BoostBook на DocBook
- bjam переводится с DocBook на HTML
Эта цепочка в настоящее время называется «make_qbk.py», скрипт Python, который вызывает цепочку выше в правильном порядке. Python гарантирует, что цепочка может обрабатываться как в средах Windows, так и в Linux (возможно также вызывать все части с помощью bjam).
Ссылочная матрица — единственное, что написано в BoostBook. Это XML-файл с обзором всего Boost. Функциональность геометрии. В QuickBook это невозможно, поэтому здесь используется BoostBook XML. Он включен в код QuickBook. Начало. Документация Asio содержит аналогичную справочную матрицу.
С Доксигеном можно определить псевдонимы. Специально для doxygen_xml2qbk был определен псевдоним \qbk{...}. Этот псевдоним \qbk{...} добавляет некоторые XML-теги вокруг текста внутри псевдонима, так что включаемая часть распознается преобразователем.
Код C++ может выглядеть так:
/*!
\brief Some explanation
\ingroup some_group
\details Some details
\tparam Geometry Description of the template parameter
\param geometry Description of the variable
\qbk{ [include reference/more_documentation.qbk] }
*/
Во-первых, вы видите нормальные комментарии. Последняя строка использует псевдоним \qbk{...} для включения файла QuickBook. Таким образом, большая часть документации может быть написана в файле QuickBook: поведение, сложность, примеры, связанные страницы и т. Д.
В приведенном выше примере используется заявление QuickBook. Но любой код QuickBook может быть использован, код QuickBook не должен храниться в отдельном файле. Еще два образца:
/*!
...
\qbk{
[heading Example]
[area_with_strategy]
[area_with_strategy_output]
[heading Available Strategies]
[link geometry.reference.strategies.strategy_area_surveyor Surveyor (cartesian)]
}
*/
В этот пример включены фрагменты QuickBook, два заголовка, два примера (это способ QuickBook - примеры определены в другом месте) и ссылка.
Есть два вопроса: запятая и звездочка. Если в псевдониме \qbk используется запятая, она распознается Doxygen как другой параметр и, следовательно, не будет доставлять правильные результаты или приводить к ошибкам. Это легко разрешимо, убегая от запятой (поставив обратную реакцию непосредственно перед запятой, \, ). Используется в псевдониме \qbk на первой строке, также интерпретируется Доксигеном. Эту звездочку также можно избежать, и на этот раз это doxygen_qbk2xml, который обрабатывает этот выход и переводит его обратно в звездочку.
Повышаю. Геометрия содержит множество перегрузок, две функции с одинаковым названием и, например, разное количество параметров. Или, как другой пример, конст и неконст версия. Они могут быть помечены специфически для инструмента doxygen_xml2qbk с псевдонимом \qbk, добавив специальное описание для перегрузки. Так, например, \qbk{отличить, со стратегией} приведет к тому, что на другой странице будет добавлен текст "со стратегией", и он будет обработан как "_with_strategy" в названии раздела QuickBook.
При перегрузках часть документации должна быть совместной, а другая часть - нет. Описания часто одинаковы. Но примеров, как правило, нет. Таким образом, это баланс между совместной документацией, включая общую документацию, избегая слишком большого количества отдельных файлов QuickBook, содержащих фрагменты документации, и избегая включения слишком большого количества кода QuickBook в код C++.
При документировании большой библиотеки неизбежно, что вы должны документировать одни и те же параметры в разных местах. Например, параметр шаблона Геометрия и переменная геометрия встречаются в нашей библиотеке не менее 100 раз.
Чтобы избежать повторения одного и того же текста снова и снова, используются псевдонимы Доксигена. Таким образом, \tparam_geometry означает, что общее описание для геометрии параметров шаблона вставлено. \param_geometry делает то же самое для параметра. Всем этим занимается сам Доксиген. Также могут быть параметризированы псевдонимы, например: \return_calc{area} расширен до: Расчетная площадь
Это относится только к Доксигену и не связано с doxygen_xml2qbk или QuickBook.
QuickBook имеет одинаковую функциональность для одной и той же цели: могут быть определены макросы или шаблоны. Внутри Роста. Геометрия используется в частях документации QuickBook. Таким образом, общее правило: там, где можно использовать псевдоним Доксиген, мы используем псевдоним Доксиген. Если мы находимся за пределами доксигена и хотим определить макрос, мы используем макрос QuickBook.
В противном случае мы не используем созданную документацию Doxygen, но если бы мы это сделали, она выглядела бы правильно и не была бы нечитаемой нерасширенными макросами QuickBook.
Мы выступаем за использование примеров кода в создаваемой документации. Примерный код должен быть правильным, поэтому примеры должны компилировать, запускать и производить правильные результаты. QuickBook имеет хорошее решение для включения и представления исходного кода C++, включая подсветку синтаксиса. Поэтому мы обычно представляем пример (полный пример, включающий необходимые заголовки) и вывод. Утверждения здесь не используются, это примеры и никаких тестов.
Вот почему мы включили в псевдоним \qbk выше:
[heading Example]
[area_with_strategy]
[area_with_strategy_output]
Мы определяем заголовок, включаем в него пример (здесь обозначается именем «area_with_strategy») и включаем вывод образца «area_with_strategy_output». Обратите внимание, что мы моделируем, что выходом является код C++, трюк, дающий соответствующее форматирование (могут быть другие способы получить тот же эффект).
Все эти примеры QuickBook включены в папки doc/src/examples/*, где также присутствует Jamfile. Бег бомжа гарантирует, что в примерах ничего не сломано.
Некоторые примеры, если они уместны, сопровождаются изображениями. Изображения генерируются самим примером (хотя и помечены как комментарии для QuickBook), доставляют файл SVG, который может быть вручную преобразован в PNG (я использую InkScape для того, что довольно удобно).
