문서 작성

QDoc 코멘트

문서는 /*! 및 */ 주석으로 구분된 QDoc 주석 안에 포함되어 있습니다. 이러한 주석은 C++ 및 QML에서 유효한 주석입니다.

QDoc 주석 내에서 //! 은 한 줄 문서 주석으로 사용되며, 주석 자체와 그 뒤의 모든 내용은 새 줄까지 생성된 출력에서 생략됩니다.

QDoc은 C++ 및 QML 파일을 파싱하여 QDoc 주석을 찾습니다. 특정 파일 유형을 명시적으로 생략하려면 구성 파일에서 해당 파일 유형을 생략하세요.

QDoc 명령

Topic 명령은 문서 요소의 유형을 결정하고, context 명령은 주제에 대한 힌트와 정보를 제공하며, markup 명령은 QDoc이 문서 형식을 지정하는 방법에 대한 정보를 제공하는 등 QDoc은 명령을 사용하여 문서에 대한 정보를 검색합니다.

QDoc 토픽

각 QDoc 댓글에는 토픽 유형이 있어야 합니다. 토픽은 다른 토픽과 구별됩니다. 주제 유형을 지정하려면 여러 주제 명령 중 하나를 사용합니다.

QDoc은 유사한 토픽을 수집하여 각 토픽에 대한 페이지를 만듭니다. 예를 들어 특정 C++ 클래스의 모든 열거형, 속성, 함수 및 클래스 설명이 한 페이지에 있습니다. 일반 페이지는 \page 명령을 사용하여 지정하며 파일 이름이 인수가 됩니다.

토픽 명령의 예

• \enum - 열거형 문서용
• \class - C++ 클래스 문서용
• \qmltype - QML 유형 문서용
• \페이지 - 페이지 생성용

QDoc 댓글에는 몇 가지 제한 사항이 있지만 같은 카테고리의 여러 토픽 명령을 포함할 수 있습니다. 이렇게 하면 함수의 모든 오버로드(여러 \fn 명령 사용) 또는 QML 속성 그룹의 모든 속성( \qmlproperty 명령 사용)을 한 번에 문서화하는 단일 주석을 작성할 수 있습니다.

QDoc 주석에 여러 주제 명령이 포함된 경우 후속 주석에서 개별 주제에 대한 추가 컨텍스트 명령을 제공할 수 있습니다:

/*!
    \qmlproperty string Type::element.name
    \qmlproperty int Type::element.id

    \brief Holds the element name and id.
*/

/*!
    \qmlproperty int Type::element.id
    \readonly
*/

여기서 후속 댓글은 element.id 속성을 읽기 전용으로 표시하고 element.name은 쓰기 가능한 상태로 유지합니다.

페이지 명령은 소스 문서의 일부가 아닌 문서를 만드는 데 사용됩니다. 이 명령은 문서의 파일 이름과 문서 유형이라는 두 가지 인수를 받을 수도 있습니다. 가능한 유형은 다음과 같습니다:

• howto
• overview
• tutorial
• faq
• attribution - 라이선스 속성 문서에 사용
• article - 유형이 없는 경우 기본값

/*!
    \page altruism-faq.html
    \title Altruism Frequently Asked Questions

    \brief All the questions about altruism, answered.

    ...
*/

토픽 명령 페이지에는 사용 가능한 모든 토픽 명령에 대한 정보가 있습니다.

토픽 컨텍스트

컨텍스트 명령은 QDoc에 토픽의 컨텍스트에 대한 힌트를 제공합니다. 예를 들어 C++ 함수가 더 이상 사용되지 않는 경우 \deprecated 명령으로 해당 함수를 표시해야 합니다. 마찬가지로 페이지 탐색 및 페이지 제목은 QDoc에 추가 페이지 정보를 제공합니다.

QDoc은 이러한 컨텍스트에 대한 추가 링크 또는 페이지를 만듭니다. 예를 들어 \group 명령을 사용하여 그룹을 만들고 구성원에게 \ingroup 명령을 사용합니다. 그룹 이름은 인수로 제공됩니다.

컨텍스트 명령 페이지에는 사용 가능한 모든 컨텍스트 명령의 목록이 있습니다.

문서 마크업

QDoc은 다른 마크업 또는 문서 도구와 유사하게 텍스트 마크업을 수행할 수 있습니다. b 명령으로 텍스트를 마크업하면 QDoc은 텍스트 섹션을 굵은 글씨로 표시할 수 있습니다.

\b{This} text will be in \b{bold}.

마크업 명령 페이지에는 사용 가능한 마크업 명령의 전체 목록이 있습니다.

문서의 해부학

기본적으로 QDoc이 페이지를 만들려면 몇 가지 필수 요소가 있어야 합니다.

• QDoc 댓글에 주제 할당 - 댓글은 페이지, 속성 문서, 클래스 문서 또는 사용 가능한 모든 주제 명령이 될 수 있습니다.
• 주제에 컨텍스트 부여 - 문서에 \deprecated로 표시된 경우 더 이상 사용되지 않는 함수를 연결하는 등 특정 주제를 다른 페이지에 연결할 수 있습니다.
• 마크업 명령으로 문서 섹션 표시하기 - QDoc은 레이아웃을 만들고 문서에 대한 문서 서식을 지정할 수 있습니다.

Qt에서 QVector3D 클래스는 다음과 같은 QDoc 주석으로 문서화되었습니다:

/*!
    \class QVector3D
    \brief The QVector3D class represents a vector or vertex in 3D space.
    \since 4.6
    \ingroup painting-3D

    Vectors are one of the main building blocks of 3D representation and
    drawing.  They consist of three coordinates, traditionally called
    x, y, and z.

    The QVector3D class can also be used to represent vertices in 3D space.
    We therefore do not need to provide a separate vertex class.

    \note By design values in the QVector3D instance are stored as \c float.
    This means that on platforms where the \c qreal arguments to QVector3D
    functions are represented by \c double values, it is possible to
    lose precision.

    \sa QVector2D, QVector4D, QQuaternion
*/

생성자 QVector3D::QVector3D()가 있으며, 이 생성자는 다음과 같은 QDoc 주석으로 문서화되었습니다:

/*!
    \fn QVector3D::QVector3D(const QPoint& point)

    Constructs a vector with x and y coordinates from a 2D \a point, and a
    z coordinate of 0.
*/

다른 주석은 다른 파일에 있을 수 있으며 QDoc은 주제와 컨텍스트에 따라 주석을 수집합니다. 스니펫의 결과 문서는 QVector3D 클래스 문서로 생성됩니다.

문서가 소스 코드에서 함수나 클래스 바로 앞에 오는 경우에는 토픽이 없어도 됩니다. QDoc은 코드 위에 있는 문서가 해당 코드에 대한 문서라고 가정합니다.

페이지 명령을 사용하여 문서를 만듭니다. 첫 번째 인수는 QDoc이 생성할 HTML 파일입니다. 이 항목은 컨텍스트 명령인 \title 및 \nextpage 명령으로 보완됩니다. list 명령과 같은 몇 가지 다른 QDoc 명령이 있습니다.

/*!
    \page generic-guide.html
    \title Generic QDoc Guide
    \nextpage Creating QDoc Configuration Files
    There are three essential materials for generating documentation with QDoc:

    \list
        \li \c QDoc binary (\c {qdoc})
        \li \c qdocconf configuration files
        \li \c Documentation in \c C++, \c QML, and \c .qdoc files
    \endlist
*/

토픽 명령에 대한 섹션에서는 다른 여러 토픽 유형에 대한 개요를 제공합니다.