Skip to content

Doxygen

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

\code [ '{'<word>'}']와 같이 사용하면 된다. 

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

Template

최초 Doxyfile을 만들면 우선적으로 수정하는 속성은 아래와 같다. 

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

사용자 정의 명령어를 추가하고 싶을 경우 Doxyfile에 ALIASES를 사용하면 된다.

아래의 예제는 두 개의 인자를 같는 translate 명령어를 추가하는 방법이다. 

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

이 후, 아래와 같이 사용하면 된다. 

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

인자를 구분하는 방법은 콤마(,)이다. 이 문자를 삽입하고 싶다면 아래와 같이 사용하면 된다. 

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

Python comments

Python은 두 가지 방법으로 주석을 남길 수 있다. 

## 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

중요한 점은 """ ~ """로 주석을 사용할 경우 """!로 시작해야 한다.

Macro 확장

C/C++에서 코드상에 존재하는 매크로를 치환한 후 Doxygen 문서화에 적용하고 싶을 경우 아래와 같이 설정하면 된다. 

MACRO_EXPANSION = YES

LaTex

TeX을 사용하고 싶다면 로컬 머신에 직접 설치하거나, MathJax를 사용하면 된다. 참고로 MathJax를 사용하는 방법은 아래와 같다. 

USE_MATHJAX = YES

예제는 아래와 같다. 

/**
 * 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 ↩