문서 분류

사전 정의된 문서 범주 또는 유형에는 다음과 같은 것들이 있습니다:

• 문서
• C++ API 문서
• QML 타입 문서
• 코드 예제

QDoc은 유형에 따라 페이지 서식을 지정할 수 있습니다. 또한 스타일시트를 사용하면 각 범주의 표시 방식을 추가로 제어할 수 있습니다.

API 문서

QDoc은 소스 코드 세트와 QDoc 주석에 포함된 문서를 바탕으로 API 문서를 생성하는 데 탁월합니다. 특히, QDoc은 Qt의 아키텍처를 인식하며 Qt C++ 클래스, 함수 또는 속성 문서의 존재 여부를 검증할 수 있습니다. QDoc은 문서를 코드 엔티티와 연결할 수 없거나 코드 엔티티에 문서가 없는 경우 경고 및 오류를 표시합니다.

일반적으로 속성, 클래스, 메서드, 시그널, 열거형과 같은 모든 Qt 코드 엔티티에는 해당 주제에 대한 명령어가 있습니다. QDoc은 C++ 명명 규칙을 사용하여 문서를 소스 코드와 연결합니다.

QDoc은 헤더 파일(일반적으로 .h 파일)을 파싱하여 클래스 구조의 트리를 구축합니다. 그런 다음 QDoc은 소스 파일과 문서 파일을 파싱하여 클래스 구조에 문서를 연결합니다. 그 후, QDoc은 해당 클래스에 대한 페이지를 생성합니다.

언어 스타일

양질의 API 문서를 작성하기 위해 Qt API 참조 문서는 특정 언어 지침을 따릅니다. 이 페이지의 내용은 API 문서를 작성하는 방법을 보여주는 반면, 스타일 지침은 참조 자료가 어떻게 일관된 언어 사용을 따르는지를 보여줍니다.

• C++ 문서 작성 스타일
• QML 문서 작성 스타일

QML 유형 문서화

Qt Qml 환경에서는 QML 시그널, 부착 속성(attached properties), QML 메서드와 같이 문서화해야 할 추가적인 요소들이 있습니다. 내부적으로는 Qt 기술을 사용하지만, QML API 문서는 Qt C++ API 문서와 다른 레이아웃 및 명명 규칙을 따릅니다.

QML 관련 QDoc 명령어 목록:

• \qmlattachedmethod
• \qmlattachedproperty
• \qmlattachedsignal
• \qmlvaluetype
• \qmltype - QML 타입 문서를 생성합니다
• \qmlmethod
• \qmlproperty
• \qmlsignal
• \inherits
• \qmlmodule
• \inqmlmodule
• \nativetype

QML 타입에 대한 문서를 작성하려면, 먼저 \qmltype 명령을 주제 명령으로 사용하는 QDoc 주석을 작성하십시오.

QML 파서

QML 타입이 qml 파일에 정의되어 있다면, 해당 파일에서 문서를 작성하십시오. QML 타입이 C++ 클래스로 표현되는 경우, 해당 C++ 클래스의 cpp 파일에서 문서를 작성하고 \nativetype 명령을 포함하여 C++ 클래스의 이름을 지정하십시오. QML 유형이 qml 파일에 정의되어 있는 경우, cpp 파일에서 해당 QML 유형에 대한 문서를 작성하지 마십시오.

qml 파일에서 QML 타입을 문서화할 때는 각 QDoc 주석을 해당 주석이 적용되는 엔티티 바로 위에 배치하십시오. 예를 들어, qml 파일에서 외부 QML 타입 바로 위에 \qmltype 명령(토픽 주석)이 포함된 QDoc 주석을 qml 파일 내의 최상위 QML 유형 바로 위에 배치하십시오. QML 속성을 문서화하는 주석은 속성 선언 바로 위에 배치하고, QML 신호 핸들러 및 QML 메서드에 대해서도 마찬가지로 처리하십시오. qml 파일에서 QML 속성을 문서화할 때는 일반적으로 \qmlproperty 명령을 주제 명령으로 포함하지 않습니다( cpp 파일에서 QML 타입을 문서화할 때는 반드시 포함해야 함). 이는 QML 파서가 각 QDoc 주석을 다음에 파싱하는 QML 선언과 자동으로 연관시키기 때문입니다. QML 신호 핸들러 및 QML 메서드 주석의 경우도 마찬가지입니다. 하지만 때로는 하나 이상의 \qmlproperty 명령을 주석에 포함하는 것이 유용할 때가 있습니다. 예를 들어, 속성 유형이 다른 QML 유형이고, 사용자가 해당 다른 QML 유형 내의 모든 속성이 아닌 특정 속성만 사용하기를 원할 때입니다. 하지만 별칭이 있는 속성을 문서화할 때는 해당 속성에 대한 QDoc 주석을 별칭 선언 바로 위에 배치해야 합니다. 이러한 경우, QDoc 주석에는 \qmlproperty 명령어를 포함해야 합니다. 그래야만 QDoc이 별칭이 지정된 속성의 유형을 파악할 수 있기 때문입니다.

해당 QML 유형에 대응하는 C++ 클래스의 cpp 파일(있는 경우)에서 QML 유형을 문서화할 때는, 일반적으로 각 QDoc 주석을 문서화하는 엔티티 바로 위에 배치합니다. 그러나 QDoc은 이러한 파일을 구문 분석할 때 QML 파서를 사용하지 않고(C++ 파서가 사용됨) C++ 파서를 사용하므로, 이러한 QML QDoc 주석은 cpp 파일 내 어디에나 위치할 수 있습니다. cpp 파일 내의 QML QDoc 주석은 반드시 QML topic 명령을 사용해야 한다는 점에 유의하십시오. 즉, \qmltype 명령어는 QML 타입에 대한 QDoc 주석에 반드시 포함되어야 하며, \qmlproperty 명령은 각 QML 속성 QDoc 주석에 포함되어야 합니다.

QML 모듈

QML 타입은 모듈에 속합니다. 모듈은 플랫폼과 관련된 모든 타입을 포함하거나 특정 버전의 타입을 포함할 수 있습니다 Qt Quick. 예를 들어, Qt Quick 2의 QML 타입들은 Qt Quick 2 모듈에 속하는 반면, Qt 4에서 도입된 구형 타입들을 위한 Qt Quick 1 모듈도 존재합니다.

QML 모듈을 사용하면 QML 타입을 그룹화할 수 있습니다. \qmltype topic 명령어에는 \inqmlmodule 컨텍스트 명령어를 포함해야 하며, 이를 통해 해당 타입을 QML 모듈과 연관시킵니다. 마찬가지로, \qmlmodule topic 명령어는 해당 모듈의 개요 페이지를 생성하기 위해 별도의 .qdoc 파일에 존재해야 합니다. 개요 페이지에는 QML 모듈의 QML 유형들이 나열됩니다.

따라서 QML 유형에 대한 링크에도 모듈 이름이 포함되어야 합니다. 예를 들어, TabWidget 라는 유형이 UIComponents 모듈에 있다면, UIComponents::TabWidget 로 링크되어야 합니다.

읽기 전용 및 내부 QML 속성

QDoc은 readonly 로 표시된 QML 속성을 감지합니다. 해당 속성은 반드시 값으로 초기화되어야 한다는 점에 유의하십시오.

readonly property int sampleReadOnlyProperty: 0

공개 인터페이스용으로 의도되지 않은 속성과 신호는 \internal 명령어로 표시할 수 있습니다. QDoc은 생성된 출력물에 해당 문서를 포함하지 않습니다.

기사 및 개요

문서 및 개요는 특정 주제나 개념에 대한 요약 정보를 제공하는 데 가장 적합한 글쓰기 형식입니다. 기술을 소개하거나 개념을 적용하는 방법을 논의할 수 있지만, 구체적인 단계를 지나치게 상세하게 다루지는 않습니다. 그러나 이러한 유형의 콘텐츠는 독자가 튜토리얼, 예제 및 클래스 문서와 같이 구체적인 지침과 참조 자료를 찾을 수 있는 진입점이 될 수 있습니다. 개요의 예로는 Qt Quick 에 대한 최상위 수준의 설명, 개별 모듈, 설계 원칙 또는 도구와 같은 제품 페이지가 있습니다.

문서가 기사임을 나타내려면 \page 명령어 뒤에 article 키워드를 추가합니다:

/*!
    \page overview-qt-technology.html
    \title Overview of a Qt Technology

    \brief provides a technology never seen before.

*/

'글쓰기 주제 명령어 ' 섹션에는 사용 가능한 \page 명령어 인자 목록이 나와 있습니다.

코드 예제

예제는 특정 기술이나 개념의 실제 사용법을 보여주는 효과적인 방법입니다. 미들웨어의 경우, 이는 대개 간단한 코드를 사용하는 애플리케이션 형태이며, 해당 코드가 무엇을 하는지 명확하게 설명해 줍니다. 모든 모듈, API, 프로젝트, 패턴 등에는 적어도 하나의 훌륭한 예제가 있어야 합니다.

예제에는 튜토리얼이 함께 제공될 수 있습니다. 튜토리얼은 코드를 설명하고 안내하는 역할을 하는 반면, 코드 예제는 사용자가 직접 학습할 수 있는 코드 내용입니다. 코드 예제에는 튜토리얼에 포함되지 않은 설명 텍스트가 함께 제공될 수도 있습니다.

QDoc은 \example 명령을 사용하여 설명이 포함된 예제 코드 페이지를 생성합니다.

/*!
    \title UI Components: Tab Widget Example
    \example declarative/ui-components/tabwidget

    This example shows how to create a tab widget. It also demonstrates how
    \l {Property aliases}{property aliases} and
    \l {Introduction to the QML Language#Default Properties}{default properties} can be used to collect and
    assemble the child items declared within an \l Item.

    \image qml-tabwidget-example.png
*/

QDoc은 입력 변수 exampledirs에 지정된 디렉터리를 사용하여 예제 파일을 생성할 Qt 프로젝트(.pro) 파일을 찾습니다. 생성된 HTML 파일의 파일명은 declarative-ui-components-tabwidget.html 입니다. 또한 QDoc은 모든 예제 코드를 나열합니다.