Создавая хтонических чудовищ, документируй

Samples

Check out the results of Doxyrest’ handiwork in application to a few open-source projects:

C++ libraries

OpenCV	vs
POCO Libraries	vs

Doxyrest generates a decent overview even if a project has no Doxygen documentation comments at all:

AXL

Replace Doxygen with your own generator of Doxygen-compatible XML database and apply the same pipeline for documenting APIs in other languages:

Lua libraries

Doxyrest Lua API

Doxyrest Frame Settings

The above manuals were generated from Doxy-comments inside files by using LuaDoxyXML instead of Doxygen at the first stage of the pipeline.

Jancy libraries

Jancy Standard Library

IO Ninja Jancy API

The above manuals were generated from Doxy-comments inside files by using the official Jancy compiler instead of Doxygen at the first stage of the pipeline.

To reiterate, the strongest point of the Doxyrest approach is that it’s modular and 100% customizable. You can replace the XML-generator to support new languages; you can change Sphinx themes or CSS styles to tweak the visual appearance (fonts, colors, page layout, etc), and if that doesn’t cut it, you can modify the Lua frames for more drastic effects — from tweaking the declaration coding style to changing the whole structure of documentation.

\overload [(function declaration)]

`This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.’

If the documentation for the overloaded member function is not located in front of the function declaration or definition, the optional argument should be used to specify the correct function.

Any other documentation that is inside the documentation block will by appended after the generated message.

Note 1:

You are responsible that there is indeed an earlier documented member that is overloaded by this one. To prevent that document reorders the documentation you should set to NO in this case.

Note 2:

The \overload command does not work inside a one-line comment.

Example:

class Test 
{
  public:
    void drawRect(int,int,int,int);
    void drawRect(const Rect &r);
};

void Test::drawRect(int x,int y,int w,int h) {}
void Test::drawRect(const Rect &r) {}

/*! \class Test
 *  \brief A short description.
 *   
 *  More text.
 */

/*! \fn void Test::drawRect(int x,int y,int w,int h)
 * This command draws a rectangle with a left upper corner at ( \a x , \a y ),
 * width \a w and height \a h. 
 */

/*!
 * \overload void Test::drawRect(const Rect &r)
 */

Click here
for the corresponding HTML documentation that is generated by doxygen.

\mainpage [(title)]

If the \mainpage command is placed in a comment block the block is used to customize the index page (in HTML) or the first chapter (in ).

The title argument is optional and replaces the default title that doxygen normally generates. If you do not want any title you can specify as the argument of \mainpage.

Here is an example:

/*! \mainpage My Personal Index Page
 *
 * \section intro Introduction
 *
 * This is the introduction.
 *
 * \section install Installation
 *
 * \subsection step1 Step 1: Opening the box
 *  
 * etc...
 */

You can refer to the main page using \ref index (if the treeview is disabled, otherwise you should use \ref main).

See also:

section , section and section .

Пакет Doxygen-1.7.5

Знакомимся с пакетом Doxygen

В пакете Doxygen находится система документирования для C++, C, Java, Objective-C, Corba IDL и
некоторых расширений PHP, C# и D. Он используется для генерации HTML-документации и/или полного неонлайнового руководства по использованию, строящегося из набора документированных исходных кодов. Есть также также поддержка создания выходных документов в формате RTF, PostScript, PDF с гиперссылками, сжатом HTML и страниц man для Unix. Документация извлекается напрямую из исходных кодов, в результате становится проще поддерживать соответствие документации исходному коду.

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

Известно, что пакет правильно собирается и работает на платформе LFS-7.0.

Информация о пакете

• Загрузка (HTTP):
• Контрольная сумма MD5: 40912d0a4b8248d78df6f705837dcd80
• Размер загружаемого пакета: 4,5 MB
• Оценочный размер требуемого дискового пространства: 74 MB
• Оценочное время сборки: 2,0 SBU (включая сборку графического интерфейса и всей документации)

Необязательные

Qt-4.7.1 (для doxywizard), Graphviz-2.26.3, Python-2.7.2, TeX Live-20110705,GPL Ghostscript-9.04

Замечания для пользователей:

Установка пакета Doxygen

Если у вас установлены оба пакета Qt-3.3.8d и Qt-4.7.1 и вы добавили параметр , то не забудьте установить переменную окружения QTDIR, которая должна указывать на директорий верхнего уровня Qt4.

Установите пакет Doxygen с помощью следующих команд:

./configure --prefix /usr \
            --docdir /usr/share/doc/doxygen-1.7.5 &&
make

Теперь в роли пользователя выполните:

make install

Если вы хотите создать и установить документацию к пакету (обратите внимание, что страницы man уже установлены), у вас должны быть установлены пакеты Python, teTeX или TeX Live (для долкументов на HTML) и Ghostscript (для документов на PDF), затем в роли пользователя выполните следующую команду:

make install_docs

Пояснение команды

: Используйте этот параметр, если у вас установлен пакет Qt4 и вы хотите собрать графический интерфейс.

Конфигурирование пакета Doxygen

Для пакета Doxygen не требуется никакого реального конфигурирования,
хотя в случае, если вы хотите использовать расширенные возможности, необходимы три дополнительных пакета. Если вам необходимо использовать возможности, предназначенные для выполнения перевода, у вас должен быть установлен пакет Python-2.7.2. Если вам требуется в документации PDF создавать формулы, то у вас должен быть установлен пакетTeX Live-20110705. Если вам требуется преобразовывать формулы из файлов PostScript в растровые изображения, то у вас должен быть установлен пакет GPL Ghostscript-9.04.

Описание пакета

Установленные программы: doxygen, doxytag и, возможно, doxywizard

Установленные библиотеки: Нет

Установленные директории: /usr/share/doc/doxygen

Краткое описание

doxygen	является утилитой командной строки, используемой для создания шаблонов конфигурационных файлов, а затем генерации документации по этим шаблонам. Используйте doxygen —help для объяснения параметров командной строки
doxytag	используется для генерации файла тегов и/или поиска файла index в наборе файлов HTML
doxywizard	является графическим интерфейсом, используемым для конфигурирования и запуска doxygen

Перевод сделан с варианта оригинала, датированного 2011-12-05 22:58:00 +0000

Предыдущий раздел:	Оглавление	Следующий раздел:
Пакет DejaGnu-1.5		Пакет Expect-5.45

Features Available by Using Sphinx / Breathe / Exhale by way of reStructuredText¶

Especially if you already know Markdown, reStructuredText syntax can be a little
frustrating. I love both equally for different reasons, but certain actions had to take
place in writing Exhale that necessitate using reStructuredText. The following is a
mini-guide on the syntax, with links to more resources.

Basic Formatting

Bold Text

Bold text is done with two asterisks: .

Italic Text

Italic text is done with one asterisk: .

Danger

Unlike most Markdown parsers, with underscores is not going to
work. It has to do with how hyperlinks work.

Teletype text is done with two backticks:

Danger

Single backticks will not do teletype text! This also has to do with how
hyperlinks in reStructuredText work.

Tables

Tip

Everything from here on may cause issues with Doxygen. Use the verbatim
environment described in the section.

Use !!!

Useful Directives

reStructuredText is particularly sensitive to whitespace. Where directives are
concerned, it may be uncomfortable for you but you actually indent by three spaces.
The reason is simple: it lines up visually.

Every directive starts with two , followed by a single space, then the directive,
followed by two . So it looks like this:

.. directive:: primary argument
   :specifications:

   There is exactly *ONE* blank line between the specifications and the text that is
   a part of the directive.

1. Not every directive requires (or supports) a primary argument.

2. Not every directive requires (or supports) specifications.

Admonitions

Sphinx enables you to include a few different admonitions. Note that which
you choose in determines how they are displayed. With the
admonitions, there are no arguments or specifications. If it is a short note you can
specify it all on one line. If it is longer, make sure you keep the blank line
between the directive and the text.

Note

.. note::

   This is a note!

Tip

.. tip::

   This is a tip!

Warning

.. warning::

   This is a warning!

Danger

.. danger::

   This is a danger (aka super-warning)!

Indexing / Including Other Files

The two directives you will use for this will be and
.

Toctrees are “Table of Contents” trees. See the .

I learned of the directive by way of writing Exhale, and call
attention to it because of the and
specifiers. It’s particularly nice to use in order to have a shared
for your code and documentation.

View the source code of exhale/docs/index.rst to see how that works.

Code Listings

If you hail from Markdown, keep in mind that it’s actually very similar. Instead of
using fenced code blocks, you’re using a directive.

.. code-block:: cpp

   // This code is highlighted using the cpp lexer
   void foo() { /* ... */ }

results in

// This code is highlighted using the cpp lexer
void foo() { /* ... */ }

You have another option, which is to use two colons after a paragraph and then
indent by four spaces. This is also similar to Markdown, only the two colons
are required. The downside to this approach is you are at the disposal of Sphinx to
determine what the language is.

This is a paragraph::

    def foo():
        pass

This is a paragraph:

def foo():
    pass

Noting that in the above output there is a single after .

\page (title)

Example:

/*! \page page1 A documentation page
  Leading text.
  \section sec An example section
  This page contains the subsections \ref subsection1 and \ref subsection2.
  For more info see page \ref page2.
  \subsection subsection1 The first subsection
  Text.
  \subsection subsection2 The second subsection
  More text.
*/

/*! \page page2 Another page
  Even more info.
*/

Click here
for the corresponding HTML documentation that is generated by doxygen.

Note:

The <name> argument consists of a combination of letters and number digits. If you wish to use upper case letters (e.g. ), or mixed case letters (e.g. ) in the <name> argument, you should set to . However, this is advisable only if your file system is case sensitive. Otherwise (and for better portability) you should use all lower case letters (e.g. ) for <name> in all references to the page.

See also:

section , section , and section .

What is Doxygen, and How do I Approach it?¶

Doxygen is a documentation (doxy) generation (gen) system. You should approach it
with fear, awe, and humility. And remember to never look it in the eyes.

Doxygen on its own is a fascinating tool. It’s stupendously flexible, and immensely
powerful. I mean let’s think about what it’s actually doing: it’s parsing and
extracting documentation from C++ (among other possible languages), which in its own
right cannot even be parsed using pushdown automata. Read this amusing SO answer
for why it’s so complex!

With a little appreciation for what Doxygen is actually doing for you, don’t take
for granted that it likely isn’t going to work perfectly out-of-the-box. It will
get most things right with almost no effort! But if your code is complicated,
expect failure, taking solace in the fact that Doxygen’s exceptional flexibility allows
for you to fix the errors.

\fn (function declaration)

onlynot

If your comment block is in front of the function declaration or definition this command can (and to avoid redundancy should) be omitted.

A full function declaration including arguments should be specified after the \fn command on a single line, since the argument ends at the end of the line!

Warning:

Do not use this command if it is not absolutely needed, since it will lead to duplication of information and thus to errors.

Example:

class Test
{
  public:
    const char *member(char,int) throw(std::out_of_range);
};

const char *Test::member(char c,int n) throw(std::out_of_range) {}

/*! \class Test
 * \brief Test class.
 *
 * Details about Test.
 */

/*! \fn const char *Test::member(char c,int n) 
 *  \brief A member function.
 *  \param c a character.
 *  \param n an integer.
 *  \exception std::out_of_range parameter is out of range.
 *  \return a character pointer.
 */

Click here
for the corresponding HTML documentation that is generated by doxygen.

See also:

section and .

\par [(paragraph title)] { paragraph }

If no paragraph title is given this command will start a new paragraph. This will also work inside other paragraph commands (like \param or \warning) without ending the that command.

The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. The \par command ends when a blank line or some other sectioning command is encountered.

Example:

/*! \class Test
 * Normal text.
 *
 * \par User defined paragraph:
 * Contents of the paragraph.
 *
 * \par
 * New paragraph under the same heading.
 *
 * \note
 * This note consists of two paragraphs.
 * This is the first paragraph.
 *
 * \par
 * And this is the second paragraph.
 *
 * More normal text. 
 */
  
class Test {};

Click here
for the corresponding HTML documentation that is generated by doxygen.

\xrefitem «(heading)» «(list title)» {text}

The first argument <key> is a identifier uniquely representing the type of the section. The second argument is a quoted string representing the heading of the section under which text passed as the forth argument is put. The third argument (list title) is used as the title for the related page containing all items with the same key. The keys «todo», «test», «bug», and «deprecated» are predefined.

To get an idea on how to use the \xrefitem command and what its effect is, consider the todo list, which (for English output) can be seen an alias for the command

 \xrefitem todo "Todo" "Todo List" 

Since it is very tedious and error-prone to repeat the first three parameters of the command for each section, the command is meant to be used in combination with the option in the configuration file. To define a new command \reminder, for instance, one should add the following line to the configuration file:

 ALIASES += "reminder=\xrefitem reminders \"Reminder\" \"Reminders\"" 

\example

If <file-name> itself is not unique for the set of example files specified by the tag, you can include part of the absolute path to disambiguate it.

If more that one source file is needed for the example, the \include command can be used.

Example:

/** A Test class.
 *  More details about this class.
 */

class Test
{
  public:
    /** An example member function.
     *  More details about this function.
     */
    void example();
};

void Test::example() {}

/** \example example_test.cpp
 * This is an example of how to use the Test class.
 * More details about this example.
 */

Where the example file looks as follows:

void main()
{
  Test t;
  t.example();
}

Click here
for the corresponding HTML documentation that is generated by doxygen.

See also:

section .

\dontinclude

The class and member declarations and definitions inside the code fragment are `remembered’ during the parsing of the comment block that contained the \dontinclude command.

For line by line descriptions of source files, one or more lines of the example can be displayed using the \line, \skip, \skipline, and \until commands. An internal pointer is used for these commands. The \dontinclude command sets the pointer to the first line of the example.

Example:

/*! A test class. */

class Test
{
  public:
    /// a member function
    void example();
};

/*! \page example
 *  \dontinclude example_test.cpp
 *  Our main function starts like this:
 *  \skip main
 *  \until {
 *  First we create a object \c t of the Test class.
 *  \skipline Test
 *  Then we call the example member function 
 *  \line example
 *  After that our little test routine ends.
 *  \line }
 */

Where the example file looks as follows:

void main()
{
  Test t;
  t.example();
}

Click here
for the corresponding HTML documentation that is generated by doxygen.

See also:

sections , , , and .

Анализ предупреждений

такоеV519

V519

V523

V523

• V523 The ‘then’ statement is equivalent to the ‘else’ statement. translator_tw.h 1956
• V523 The ‘then’ statement is equivalent to the ‘else’ statement. translator_tw.h 1965

V530

V560

V560

V595

• V595 The ‘cd’ pointer was utilized before it was verified against nullptr.
  Check lines: 6123, 6131. doxygen.cpp 6123
• V595 The ‘p’ pointer was utilized before it was verified against nullptr.
  Check lines: 1069, 1070. htmldocvisitor.cpp 1069
• V595 The ‘Doxygen::mainPage’ pointer was utilized before it was verified against nullptr.
  Check lines: 3792, 3798. index.cpp 3792
• V595 The ‘firstMd’ pointer was utilized before it was verified against nullptr.
  Check lines: 80, 93. membergroup.cpp 80
• V595 The ‘lastCompound’ pointer was utilized before it was verified against nullptr.
  Check lines: 410, 420. vhdljjparser.cpp 410
• V595 The ‘len’ pointer was utilized before it was verified against nullptr.
  Check lines: 11960, 11969. qstring.cpp 11960
• V595 The ‘len’ pointer was utilized before it was verified against nullptr.
  Check lines: 11979, 11988. qstring.cpp 11979
• V595 The ‘fd’ pointer was utilized before it was verified against nullptr.
  Check lines: 2077, 2085. doxygen.cpp 2077

V595

V601

• V601 The bool type is implicitly cast to the class type. Inspect the fifth argument. context.cpp 2315
• V601 The bool type is implicitly cast to the class type. Inspect the fifth argument. context.cpp 2675
• V601 The bool type is implicitly cast to the class type. Inspect the fifth argument. context.cpp 4456

V614

• V614 Potentially uninitialized pointer ‘tmpEntry’ used. vhdlparser.cc 4451
• V614 Potentially uninitialized pointer ‘t’ used. vhdlparser.cc 5304

V668

• V668 There is no sense in testing the ‘expr’ pointer against null, as the memory was allocated using the ‘new’ operator. The exception will be generated in the case of memory allocation error. template.cpp 1981
• V668 There is no sense in testing the ‘n’ pointer against null, as the memory was allocated using the ‘new’ operator. The exception will be generated in the case of memory allocation error. qglist.cpp 1005
• V668 There is no sense in testing the ‘nd’ pointer against null, as the memory was allocated using the ‘new’ operator. The exception will be generated in the case of memory allocation error. qstring.cpp 12099

V701

• V701 realloc() possible leak: when realloc() fails in allocating memory, original pointer ‘d’ is lost. Consider assigning realloc() to a temporary pointer. qcstring.h 396
• V701 realloc() possible leak: when realloc() fails in allocating memory, original pointer ‘str’ is lost. Consider assigning realloc() to a temporary pointer. growbuf.h 16
• V701 realloc() possible leak: when realloc() fails in allocating memory, original pointer ‘str’ is lost. Consider assigning realloc() to a temporary pointer. growbuf.h 23
• V701 realloc() possible leak: when realloc() fails in allocating memory, original pointer ‘str’ is lost. Consider assigning realloc() to a temporary pointer. growbuf.h 33
• V701 realloc() possible leak: when realloc() fails in allocating memory, original pointer ‘m_str’ is lost. Consider assigning realloc() to a temporary pointer. vhdlstring.h 61
• V701 realloc() possible leak: when realloc() fails in allocating memory, original pointer ‘shd->data’ is lost. Consider assigning realloc() to a temporary pointer. qgarray.cpp 224
• V701 realloc() possible leak: when realloc() fails in allocating memory, original pointer ‘m_data’ is lost. Consider assigning realloc() to a temporary pointer. qgstring.cpp 114
• V701 realloc() possible leak: when realloc() fails in allocating memory, original pointer ‘m_data’ is lost. Consider assigning realloc() to a temporary pointer. qgstring.cpp 145

Introduction

\@

Some commands have one or more arguments. Each argument has a certain range:

• If <sharp> braces are used the argument is a single word.
• If (round) braces are used the argument extends until the end of the line on which the command was found.
• If {curly} braces are used the argument extends until the next paragraph. Paragraphs are delimited by a blank line or by a section indicator.

Here is an alphabetically sorted list of all commands with references to their documentation:

The following subsections provide a list of all commands that are recognized by doxygen. Unrecognized commands are treated as normal text.

Quick HOWTO

Here is a list of steps required to apply Doxyrest to existing Doxygen-based projects:

1. Get Tool Binaries

Sphinx Version

Note that Doxyrest requires Sphinx or above. If the Sphinx version from the official repos of your Linux distro is below that, please use to install a newer one.

2. Prepare Configuration Files

2.1. for Doxygen

Adjust the following settings in your Doxygen configuration file :

# Obviously, we do need XML:

GENERATE_XML = YES

# You may also want to turn the generation of HTML off:
# GENERATE_HTML = NO

# Next, choose the location of the resulting XML database:

XML_OUTPUT = xml-dir

# Program listing vastly increases the size of XML so it's recommended
# to turning it OFF:

XML_PROGRAMLISTING = NO

# The next one is essential! Sphinx uses lowercase reference IDs,
# so Doxygen can't use mixed-case IDs:

CASE_SENSE_NAMES = NO

# The next one is important for C++ projects -- otherwise Doxygen
# may generate lots of bogus links to template arguments:

HIDE_UNDOC_RELATIONS = YES

# The last one is not essential, but recommended if your project
# sets AUTOLINK_SUPPORT to ON (like most projects do) -- otherwise
# auto-generated links may point to discarded items:

EXTRACT_ALL = YES

2.2. for Doxyrest

Copy the default configuration file from and adjust the necessary settings. Here’s what may need adjustment for existing Doxygen-based C/C++ projects:

-- Specify input and output paths:

OUTPUT_FILE = "rst-dir/index.rst"
INPUT_FILE = "xml-dir/index.xml"
FRAME_FILE = "index.rst.in"
FRAME_DIR_LIST = { "doxyrest-frame-dir/cfamily", "doxyrest-frame-dir/common" }

-- Usually, Doxygen-based documentation has a main page (created with
-- the \mainpage directive). If that's the case, force-include
-- the contents of 'page_index.rst' into 'index.rst':

INTRO_FILE = "page_index.rst"

-- If your documentation uses \verbatim directives for code snippets
-- you can convert those to reStructuredText C++ code-blocks:

VERBATIM_TO_CODE_BLOCK = "cpp"

-- Asterisks, pipes and trailing underscores have special meaning in
-- reStructuredText. If they appear in Doxy-comments anywhere except
-- for code-blocks, they must be escaped:

ESCAPE_ASTERISKS = true
ESCAPE_PIPES = true
ESCAPE_TRAILING_UNDERSCORES = true

2.3. for Sphinx

Finally, prepare a Sphinx configuration file . A good approach would be generating one using and then adding the following:

# Specify the path to Doxyrest extensions for Sphinx:

sys.path.insert(1, os.path.abspath('doxyrest-sphinx-dir'))

# Add Doxyrest extensions ``doxyrest`` and ``cpplexer``:

extensions += 

# If you used INTRO_FILE in 'doxyrest-config.lua' to force-include it
# into 'index.rst', exclude it from the Sphinx input (otherwise, there
# will be build warnings):

exclude_patterns += 

Standard install locations for the Doxyrest Sphinx extensions ( and ):

Windows
Linux, macOS

If in doubt, please navigate to the Doxyrest Sphinx extension directory and make sure and are there.

3. Run The Doxyrest Pipeline

After the configuration files are ready, it’s time to build:

# stage 1: generate Doxygen XML

$ doxygen Doxyfile

# stage 2: generate reStructuredText

$ doxyrest -c doxyrest-config.lua

# stage 3: generate HTML

$ sphinx-build -b html rst-dir html-dir

Now open and enjoy the new awesome look of your documentation!

4. Play With The Styles (optional)

Alright, you were able to generate HTML documentation, but you would like to tweak some styles (colors, fonts, margins, etc). With Sphinx, you can easily adjust both the theme and CSS stylesheets. Doxyrest extensions for Sphinx also allow you setting the tab-width (tab-width being hardcoded to is a longtime issue with Sphinx).

To do all that, edit your :

# Choose a Sphinx theme:

html_theme = 'sphinx_rtd_theme'

# Prepare a folder ./static/ with all the .css files you want to replace, e.g.
#     ./static/pygments.css
#     ./static/css/theme.css
#     ...
# Then ask Sphinx to write it over the standard '_static' folder:

html_static_path = ['static/']

# Specify the size of tab indentation:

doxyrest_tab_width = 2

If you use a theme other than or (natively supported by Doxyrest), make sure your stylesheets properly define the following Doxyrest-specific classes:

pre.doxyrest-overview-code-block {
        ...
}

pre.doxyrest-overview-inherited-code-block {
        ...
}

pre.doxyrest-title-code-block {
        ...
}

.doxyrest-target-highlight {
        ...
}

Use and as examples for how to do that.