Skip to content
Search

Doxygen

lastmod 2025-12-11created 2014-12-2228 edits

Doxygen is a documentation generator, a tool for writing software reference documentation. The documentation is written within code, and is thus relatively easy to keep up to date. Doxygen can cross reference documentation and code, so that the reader of a document can easily refer to the actual code.

Doxygen is free software, released under the terms of the GNU General Public License version 2 (GPLv2).

Categories

Special Commands

code

Use it like \code [ '{'<word>'}']. 

/**
 * \code{.cpp}
 * class Cpp {};
 * \endcode
 */

Template

After first creating a Doxyfile, these are the properties to modify first. 

PROJECT_NAME            = "${MAIN_NAME}"
PROJECT_NUMBER          = "${VERSION}"
PROJECT_BRIEF           = "${MAIN_BRIEF}"
OUTPUT_LANGUAGE         = Korean-en
ALIASES                 = translate{2}="<dl class='section remarks'><dt>Translate-\1</dt><dd>\2</dd></dl>"
WARN_IF_UNDOCUMENTED    = NO
INPUT                   = .
FILE_PATTERNS           = *.c *.cc *.cxx *.cpp *.c++ *.d *.java *.ii *.ixx *.ipp *.i++ \
                          *.inl *.h *.hh *.hxx *.hpp *.h++  *.idl *.odl *.cs *.php *.php3 \
                          *.inc *.m *.markdown *.md *.mm *.dox *.py *.f90  *.f *.for *.vhd *.vhdl
RECURSIVE               = YES
EXCLUDE_PATTERNS        = *3rd/* *build/* *tparty/*
HTML_TIMESTAMP          = YES
HTML_OUTPUT             = .html
GENERATE_LATEX          = NO
LATEX_OUTPUT            = .latex
#RTF_SOURCE_CODE        = NO # Doxygen v1.8.6 unsupported tag.
MACRO_EXPANSION         = YES
INCLUDE_PATH            = .
INCLUDE_FILE_PATTERNS   = *.h *.hh *.hxx *.hpp *.h++
USE_MATHJAX             = YES
MATHJAX_RELPATH         = https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML
QUIET                   = YES

Aliases

To add custom commands, use ALIASES in the Doxyfile.

The example below shows how to add a translate command that takes two arguments. 

ALIASES = translate{2}="<dl class='section remarks'><dt>Translate-\1</dt><dd>\2</dd></dl>"

Then use it as follows. 

/**
 * Time based interpolator interface.
 *
 * @translate{ko,시간에 기반하여 값을 보간하는 인터페이스를 제공한다.}
 *
 * @author yourname
 * @date   2015-06-27
 */

Arguments are separated by a comma (,). To insert this character, use it as follows. 

/**
 * @translate{ko,정상적이지 않은 상태(종료 코드가 0이 아니거나 종료 시그널이 0이 아닐 경우)로 태스크가 종료될 경우 재실행한다.\n
 *               0일 경우 이 기능을 사용하지 않고\, -1\, 'inf'\, 'infinity'일 경우 무제한으로 재실행 된다.}
 */

Python comments

In Python, comments can be written in two ways. 

## Documentation for a function.
#
#  More details.
def func():
    pass

class PyClass:
    """! Documentation for a class.

    More details.
    @author yourname
    """

    def __init__(self):
        """! The constructor."""
        self._memVar = 0;

    def PyMethod(self):
        """! Documentation for a method."""
        pass

The important point is that comments written with """ ~ """ must start with """!.

Macro expansion

In C/C++, if you want the macros in the code to be substituted before being applied to the Doxygen documentation, set the following. 

MACRO_EXPANSION = YES

LaTex

To use TeX, either install it directly on your local machine or use MathJax. For reference, here is how to use MathJax. 

USE_MATHJAX = YES

Here is an example. 

/**
 * Step by step average.
 *
 * @translate{ko, 점진적으로 평균을 구할 수 있다.}
 *
 * @remarks
 *  \f[
 *   \begin{align}
 *   c_N &= \frac{1}{N}(x_1 + x_2 + x_3 + ... + x_N) \\
 *   &= \frac{1}{N} \sum_{i=1}^{N}x_i \\
 *   &= \frac{1}{N} \left( \sum_{i=1}^{N-1}x_i + x_N \right) \\
 *   &= \frac{N-1}{N} \frac{1}{N-1} \sum_{i=1}^{N-1}x_i + \frac{1}{N}x_N
 *   \end{align}
 *  \f]
 *  아래와 같이 \f$ c_{N-1} \f$ 를 구할 수 있다. @n
 *  \f[
 *   c_{N-1} = \frac{1}{N-1} \sum_{i=1}^{N-1}x_i
 *  \f]
 *  아래와 같이 정의할 경우, @n
 *  \f[
 *   \alpha = \frac{N-1}{N}
 *  \f]
 *  아래와 같이 유도할 수 있다. @n
 *  \f[
 *   1 - \alpha = \frac{1}{N}
 *  \f]
 *  최종적으로 아래의 식이 도출된다. @n
 *  \f[
 *   \begin{align}
 *   c_N &= \frac{N-1}{N} \frac{1}{N-1} \sum_{i=1}^{N-1}x_i + \frac{1}{N}x_N \\
 *   &= \frac{N-1}{N} c_{N-1} + \frac{1}{N}x_N \\
 *   &= \alpha c_{N-1} + (1 - \alpha)x_N
 *   \end{align}
 *  \f]
 */
template <typename Base, typename Result = Base, typename Integer = int>
Result averageStep(Base prev_average, Base current, Integer n)
{
    Result const ALPHA = (static_cast<Result>(n) - static_cast<Result>(1)) / static_cast<Result>(n);
    return (ALPHA * static_cast<Result>(prev_average)) +
            ((static_cast<Result>(1) - ALPHA) * static_cast<Result>(current));
}

PlantUML 

##
# Class for default database access.
#
# @startuml
# hide circle
# skinparam linetype ortho
#
# entity "RegisteredUser" as reg_user {
#     * id: int <<generated>>
#     --
#     * user_id: text
#     user_token: text
#     active_duration: int
#     max_count: int
#     features: text
#     --
#     create_date: date
#     update_date: date
# }
#
# entity "CertificateInfo" as cert_info {
#     * id: int <<generated>>
#     --
#     * user_id: text <<FK>>
#     request_date: date
#     approval_date: date
#     deadline: date
#     session_key: text
#     machine_id: text
#     product_uuid: text
#     software_tbag: text
#     software_core: text
#     remote_ip: text
#     key: text
#     iv: text
#     --
#     create_date: date
#     update_date: date
# }
#
# reg_user  ||--o{  cert_info
#
# @enduml
class Database:

    def __init__(self, host, port, dbname, user, password):
        self.connection = create_database_connection(host, port, dbname, user, password)
        self.cursor = self.connection.cursor()

Mscgen 

/// @brief Ping request.
///
/// 노드(Node) 및 테스크(Task)의 활성 상태를 확인한다.
///
/// '활성상태'란 소켓 및 프로세스(또는 스레드)의 활성화 상태 뿐 아니라
/// 내부적인 정합성(Validation) 검증이 완료되었음을 나타낸다.
///
/// @par Node directory hierarchy
///  {TASK}.{LAMBDA}.{BOX}
///
/// @par Task directory hierarchy
///  {LAMBDA}.{BOX}
///
/// 테스크(Task) 상태를 노드(Node)에 요청할 경우, 내부적으로 아래와 같이 재 요청이 발생된다.
/// @msc
///   Client,Node,Task;
///   Client->Node [label="PingQ"];
///   Node->Task [label="PingQ"];
///   Node<-Task [label="PingA"];
///   Client<-Node [label="PingA"];
/// @endmsc
///
/// 따라서 가급적 테스크(Task)의 관리자 소켓에 직접 요청하는 것이 성능적 이점이 많다.
///
/// @ingroup msg
/// @hidecallergraph
/// @hidecallgraph
///
/// @see PingA
///
/// @author yourname
/// @date 2019-08-14
///
struct PingQ
{
    /// @brief Query string.
    ///
    /// 쿼리 문자열.
    ///
    /// 빈 문자열을 사용할 경우 해당되는 소켓의 그 자체의 활성상태를 점검한다.
    ///
    char * query;
};

See also

Favorite site

Doxygen manual

Guide

References

  1. Doxygen_manual-1.8.3.1.pdf ↩

  2. Blog.naver.com_-syleenet-_How_to_use_doxygen.pdf ↩

  3. Doxygen_apply_1.pdf ↩

  4. Doxygen_apply_2.pdf ↩

  5. Doxygen_apply_3.pdf ↩

  6. Doxygen_guide.pdf ↩

author Zer0 sitemap