문서 작성

QDoc 주석

문서는 /*! 및 */ 주석으로 구분되는 QDoc 주석 내에 포함됩니다. 이 주석들은 C++ 및 QML에서 유효한 주석임을 유의하십시오.

QDoc 주석 내에서 ` //! `는 한 줄짜리 문서 주석으로 사용되며, 주석 자체와 그 뒤에 이어지는 내용(줄바꿈까지)은 생성된 출력에서 생략됩니다.

QDoc은 C++ 및 QML 파일을 분석하여 QDoc 주석을 찾습니다. 특정 파일 유형을 명시적으로 제외하려면 구성 파일에서 해당 파일 유형을 제외하십시오.

QDoc 명령어

QDoc은 명령어를 사용하여 문서에 대한 정보를 가져옵니다. ` Topic ` 명령어는 문서 요소의 유형을 판별하고, ` context ` 명령어는 주제에 대한 힌트와 정보를 제공하며, ` markup ` 명령어는 QDoc이 특정 문서 부분을 어떻게 서식 지정해야 하는지에 대한 정보를 제공합니다.

QDoc 주제

각 QDoc 주석에는 주제 유형이 반드시 지정되어야 합니다. 주제는 해당 주석을 다른 주제와 구별해 줍니다. 주제 유형을 지정하려면 여러 주제 명령어 중 하나를 사용합니다.

QDoc은 유사한 주제들을 모아 각 주제마다 별도의 페이지를 생성합니다. 예를 들어, 특정 C++ 클래스의 모든 열거형, 속성, 함수 및 클래스 설명은 하나의 페이지에 포함됩니다. 일반 페이지는 \page 명령을 사용하여 지정하며, 파일명이 인수로 사용됩니다.

주제 명령어의 예:

• \enum - 열거형 문서화의 경우
• \class - C++ 클래스 문서용
• \qmltype - QML 타입 문서용
• \page - 페이지 생성을 위한 것.

여러 주제

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은 여전히 쓰기 가능하게 유지합니다.

'주제 명령어 ' 페이지에는 사용 가능한 모든 주제 명령어에 대한 정보가 있습니다.

주제 컨텍스트

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

QDoc은 이러한 컨텍스트에 대해 추가 링크나 페이지를 생성합니다. 예를 들어, \group 명령어를 사용하여 생성되며, 멤버들은 \ingroup 명령어를 갖습니다. 그룹 이름은 인수로 전달됩니다.

'컨텍스트 명령 ' 페이지에는 사용 가능한 모든 컨텍스트 명령이 나열되어 있습니다.

문서 마크업

QDoc은 다른 마크업 또는 문서화 도구와 유사하게 텍스트를 마크업할 수 있습니다. QDoc은 텍스트가 \b 명령어로 마크업된 경우, 해당 텍스트 부분을 굵게 표시할 수 있습니다.

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

'서식 지정 명령어' 페이지에는 사용 가능한 모든 서식 지정 명령어가 상세히 나열되어 있습니다.

문서의 구조

기본적으로 QDoc이 페이지를 생성하려면 몇 가지 필수 요소가 존재해야 합니다.

• QDoc 주석에 주제 할당 - 주석은 페이지, 속성 문서, 클래스 문서 또는 사용 가능한 주제 명령어 중 하나일 수 있습니다.
• 주제에 컨텍스트 지정 — QDoc은 특정 주제를 다른 페이지와 연관시킬 수 있습니다. 예를 들어, 문서에 \deprecated로 표시된 문서에 사용되지 않는 요소를 연결하는 것과 같이, 특정 주제를 다른 페이지와 연관시킬 수 있습니다.
• 문서의 섹션에 마크업 명령을 지정 - QDoc은 레이아웃을 생성하고 문서의 서식을 지정할 수 있습니다.

Qt XML에서 ` 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은 코드 위의 설명이 해당 코드에 대한 설명이라고 간주합니다.

문서는 \page 명령어를 사용하여 생성됩니다. 첫 번째 인수는 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
*/

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