문서 카테고리

미리 정의된 문서 카테고리 또는 유형에는 여러 가지 유형이 있습니다:

• How-To
• 튜토리얼
• 개요
• 문서
• FAQ(자주 묻는 질문)
• 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 유형 문서화

QML 세계에는 QML 신호, 첨부된 프로퍼티, QML 메서드 등 문서화해야 할 추가 엔티티가 있습니다. 내부적으로는 Qt 기술을 사용하지만, QML API 문서에는 Qt C++ API 문서와는 다른 레이아웃과 명명 규칙이 필요합니다.

QML 관련 QDoc 명령 목록입니다:

• \qmlattachedproperty
• \qmlattachedsignal
• \qmlvaluetype
• \qmltype - QML 유형 문서를 생성합니다.
• \qmlmethod
• \qmlproperty
• \qmlsignal
• \상속
• \qmlmodule
• \inqmlmodule
• \네이티브타입

QML 유형을 문서화하려면 먼저 \qmltype 명령을 주제 명령으로 사용하는 QDoc 주석을 만드세요.

QML 파서

QML 유형이 qml 파일에 정의되어 있는 경우 해당 파일에 문서화하세요. QML 유형이 C++ 클래스로 표현되는 경우 해당 C++ 클래스의 cpp 파일에 문서화하고 \nativetype 명령을 포함하여 C++ 클래스 이름을 지정하세요. QML 유형이 qml 파일에 정의되어 있는 경우 cpp 파일에 QML 유형을 문서화하지 마세요.

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

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

QML 모듈

QML 유형은 모듈에 속합니다. 모듈은 플랫폼에 대한 모든 관련 유형을 포함하거나 특정 버전의 Qt Quick. 예를 들어, Qt Quick 2 QML 유형은 Qt Quick 2 모듈에 속하며, Qt 4에 도입된 이전 유형에 대한 Qt Quick 1 모듈도 있습니다.

QML 모듈을 사용하면 QML 유형을 그룹화할 수 있습니다. qmltype 주제 명령에는 해당 유형을 QML 모듈과 연관시키기 위한 \inqmlmodule 컨텍스트 명령이 있어야 합니다. 마찬가지로 모듈에 대한 개요 페이지를 만들려면 별도의 .qdoc 파일에 \qmlmodule 주제 명령이 있어야 합니다. 개요 페이지에는 QML 모듈의 QML 유형이 나열됩니다.

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

읽기 전용 및 내부 QML 속성

QDoc은 readonly 로 표시된 QML 속성을 감지합니다. 프로퍼티는 값으로 초기화되어야 합니다.

readonly property int sampleReadOnlyProperty: 0

공개 인터페이스용이 아닌 속성 및 신호는 \internal 명령으로 표시할 수 있습니다. QDoc은 생성된 출력에 문서를 게시하지 않습니다.

문서 및 개요

문서 및 개요는 주제나 개념에 대한 요약 세부 정보를 제공하는 데 가장 적합한 글쓰기 스타일입니다. 기술을 소개하거나 개념을 적용하는 방법을 논의할 수 있지만 정확한 단계를 너무 자세히 설명하지는 않습니다. 그러나 이러한 유형의 콘텐츠는 독자가 튜토리얼, 예제 및 수업 문서와 같은 교육 및 참고 자료를 찾을 수 있는 시작점을 제공할 수 있습니다. 개요의 예로는 Qt Quick, 개별 모듈, 디자인 원칙 또는 도구에 대한 최상위 수준의 토론과 같은 제품 페이지를 들 수 있습니다.

문서가 문서임을 표시하려면 \page 명령에 문서 키워드를 추가하면 됩니다:

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

    \brief provides a technology never seen before.

*/

문서 작성 명령어 섹션에는 사용 가능한 \page 명령어 인수의 목록이 있습니다.

튜토리얼, 사용법, FAQ

튜토리얼, 사용법 및 FAQ는 독자에게 지시하거나 처방한다는 점에서 모두 교육용 자료입니다. 튜토리얼은 개념이나 기술에 대한 점진적인 학습 경로를 따라 독자를 안내하기 위해 고안된 콘텐츠입니다. 방법 및 FAQ(자주 묻는 질문)는 자주 묻는 주제에 대한 답변 형식으로 자료를 제시하여 지침을 제공합니다. 방법 및 FAQ는 쉽게 참조할 수 있도록 만들어졌으며 반드시 선형적인 진행 순서로 표시되지는 않습니다.

이러한 유형을 만들려면 \page 명령에 type 인수를 제공하여 페이지를 표시합니다. type 인수는 두 번째 인수가 되고 파일 이름은 첫 번째 인수가 됩니다.

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

    \brief All the questions about altruism, answered.

    ...
*/

토픽 명령어 쓰기 섹션에 사용 가능한 \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에는 모든 예제 코드도 나열됩니다.