이 명령어들은 문서의 시각적 모양과 문서 생성 과정과 관련된 다양한 기능을 제공합니다.

\annotatedlist

\annotatedlist 명령어는 그룹의 구성원 목록으로 확장되며, 각 구성원은 간단한 설명과 함께 나열됩니다. 다음은 Qt 참조 문서에서 가져온 예시입니다:

/*!
   ...
   \section1 Drag and Drop Classes

   These classes deal with drag and drop and the necessary mime type
   encoding and decoding.

   \annotatedlist draganddrop
*/

이렇게 하면 draganddrop 그룹에 속한 모든 C++ 클래스 및/또는 QML 유형의 목록이 생성됩니다. draganddrop 그룹에 속한 C++ 클래스나 QML 유형은 \ingroup draganddrop을 \class 또는 \qmltype 주석에 'draganddrop'이 포함됩니다.

그룹 구성원은 사용자에게 표시되는 이름이나 제목을 기준으로 오름차순으로 정렬됩니다. QDoc 6.8부터는 \annotatedlist 및 \generatelist 사용자 정의 정렬도 지원합니다.

참조: \generatelist 및 ‘그룹 구성원 정렬’을 참조하십시오.

\cmakepackage

\cmakepackage 명령어를 사용하여 클래스 및 네임스페이스에 CMake 패키지 정보를 추가할 수 있습니다. 이 정보는 클래스 또는 네임스페이스 문서 페이지 상단의 표에 표시됩니다. 예를 들어:

/*!
    \namespace Foo
    \inheaderfile Bar
    \cmakepackage Baz
    \brief A namespace.

    ...
*/

QDoc은 이를 다음과 같이 출력합니다.

Foo 네임스페이스

A 네임스페이스. 더 보기...

헤더:	#include <Bar>
CMake:	find_package(Baz REQUIRED) target_link_libraries(mytarget PRIVATE Baz::Baz)

참조 \module 및 \cmakecomponent}

\cmakecomponent

\cmakecomponent 명령어를 사용하여 클래스 및 네임스페이스에 CMake 구성 요소 정보를 추가할 수 있습니다. 이 정보는 클래스 또는 네임스페이스 문서 페이지 상단의 표에 표시됩니다. 예를 들어:

/*!
    \namespace Foo
    \inheaderfile Bar
    \cmakecomponent Baz
    \brief A namespace.

    ...
*/

QDoc은 이를 다음과 같이 출력합니다.

Foo 네임스페이스

A 네임스페이스. 더 보기...

헤더:	#include <Bar>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Baz) target_link_libraries(mytarget PRIVATE Qt6::Baz)

참조 \module 및 \cmakepackage}

\cmaketargetitem

\cmaketargetitem 명령어를 사용하여 클래스와 네임스페이스에 추가되는 CMake target_link_libraries 정보 중 항목 부분을 재정의할 수 있습니다. 이 명령어는 \module 및 \cmakecomponent 명령과 함께 사용해야 합니다. 예를 들면 다음과 같습니다:

/*!
    \namespace Foo
    \inheaderfile Bar
    \cmakecomponent Baz
    \cmaketargetitem Qt6::BazPrivate
    \brief A namespace.

    ...
*/

QDoc은 이를 다음과 같이 출력합니다.

Foo 네임스페이스

A 네임스페이스. 더 보기...

헤더:	#include <Bar>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Baz) target_link_libraries(mytarget PRIVATE Qt6::BazPrivate)

참조 \module 및 \cmakecomponent}

\qtcmakepackage

\qtcmakepackage 명령어를 사용하여 클래스 및 네임스페이스에 CMake 패키지 정보를 추가할 수 있습니다. 이 정보는 클래스 또는 네임스페이스 문서 페이지 상단의 표에 표시됩니다. 예를 들어:

/*!
    \namespace Foo
    \inheaderfile Bar
    \qtcmakepackage Baz
    \brief A namespace.

    ...
*/

QDoc은 이를 다음과 같이 출력합니다.

Foo 네임스페이스

A 네임스페이스. 더 보기...

헤더:	#include <Bar>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Baz)

\qtcmaketargetitem

\qtcmaketargetitem 명령어를 사용하여 클래스와 네임스페이스에 추가되는 CMake target_link_libraries 정보의 항목 부분을 재정의할 수 있습니다. 이 명령어는 반드시 \module 및 \qtcmakepackage 명령과 함께 사용해야 합니다.

참조 \module 및 \qtcmakepackage}

\generatelist

\generatelist 명령어는 아래에 나열된 인자 중 하나와 일치하는 \ingroup 명령어로 그룹화된 문서 엔티티 목록이나, 아래 나열된 인자 중 하나와 일치하는 엔티티 목록으로 확장됩니다. Qt 참조 문서의 예시:

/*!
   \page classes.html
   \title All Classes

   For a shorter list that only includes the most
   frequently used classes, see \l{Qt's Main Classes}.

   \generatelist classes Q
*/

이렇게 하면 ‘모든 클래스(All Classes )’ 페이지가 생성됩니다. 이 명령어는 다음 인수를 지원합니다:

<group-name>

그룹 이름을 유일한 인수로 지정하면, QDoc은 \ingroup <group-name> 명령을 사용하는 모든 엔티티를 나열합니다.

그룹 구성원 정렬

그룹 구성원 목록을 생성할 때, 구성원들은 사용자에게 표시되는 이름이나 제목을 기준으로 오름차순으로 정렬됩니다. QDoc 6.8부터는 기본 정렬 순서를 변경할 수 있습니다:

\generatelist [descending] changelogs

'changelogs' 그룹이 각 버전의 변경 사항을 상세히 설명하는 페이지들로 구성되어 있다고 가정할 때, 이 설정은 목록을 내림차순(최신 버전 순)으로 생성합니다.

정렬 기준

QDoc 6.8부터는 \meta 명령을 사용하여 하나 이상의 그룹 구성원에게 사용자 정의 정렬 키를 할당할 수 있습니다:

\meta sortkey {sort key}

그러면 정렬(오름차순 또는 내림차순)은 사용자에게 표시되는 제목이 아닌 이러한 키를 기준으로 수행됩니다.

annotatedclasses

annotatedclasses 인수는 모든 클래스의 이름과 각 클래스에 대한 설명이 포함된 테이블을 제공합니다. 각 클래스 이름은 해당 클래스의 참조 문서로 연결되는 링크입니다. 예를 들면 다음과 같습니다:

C++ 클래스는 \class 명령어로 문서화됩니다. 클래스에 대한 주석은 클래스 주석의 \brief 명령의 인자로부터 가져옵니다.

annotatedexamples

annotatedexamples 인수는 모든 예제의 제목과 각 예제에 대한 설명이 포함된 일련의 표 형태로 모든 예제의 전체 목록을 제공합니다. 각 제목은 해당 예제의 문서로 연결되는 링크입니다.

(문서화된 예제가 있는) 각 모듈에 대해 별도의 표가 생성되며, 이는 해당 모듈에 navigation.landingpage 구성 변수가 정의되어 있는 경우에 한합니다. landingpage 변수는 각 표 앞에 표시되는 헤더의 제목으로 사용됩니다.

annotatedattributions

annotatedattributions 인수는 모든 출처 정보의 제목과 각 출처 정보에 대한 설명을 포함하는 일련의 표 형태로 전체 목록을 제공합니다. 각 제목은 해당 출처 정보 페이지로 연결되는 링크입니다.

모듈에 navigation.landingpage 구성 변수가 정의되어 있는 경우, (저작자 표시가 있는) 각 모듈에 대해 별도의 표가 생성됩니다. landingpage 변수는 각 표 앞에 표시되는 헤더의 제목으로 사용됩니다.

classes <prefix>

classes 인수는 클래스의 전체 목록을 알파벳순으로 제공합니다. 두 번째 인자 <prefix> 는 클래스 이름의 공통 접두사입니다. 클래스 이름은 공통 접두사 다음에 오는 문자를 기준으로 정렬됩니다. 예: Qt 클래스의 공통 접두사는 Q 입니다. 공통 접두사 인자는 선택 사항입니다. 공통 접두사가 지정되지 않은 경우, 클래스 이름은 첫 번째 문자를 기준으로 정렬됩니다.

각 클래스 이름은 해당 클래스의 참조 문서로 연결되는 링크가 됩니다. 이 명령은 다음과 같은 방식으로 ‘모든 클래스(All Classes )’ 페이지를 생성하는 데 사용됩니다:

/*!
    \page classes.html
    \title All Classes
    \ingroup classlists

    \brief Alphabetical list of classes.

    This is a list of all Qt classes. For classes that
    have been deprecated, see the \l{Obsolete Classes}
    list.

    \generatelist classes Q
*/

C++ 클래스의 문서는 \class 명령어로 문서화됩니다.

classesbymodule

이 인수를 사용할 때는, 나열할 클래스가 포함된 모듈을 지정하는 두 번째 인수가 필요합니다. QDoc은 해당 클래스들이 포함된 표를 생성합니다. 각 클래스는 해당 \brief 명령어의 텍스트와 함께 나열됩니다.

예를 들어, 이 명령은 모듈 페이지에서 다음과 같이 사용할 수 있습니다:

/*!
    \page phonon-module.html
    \module Phonon
    \title Phonon Module
    \ingroup modules

    \brief Contains namespaces and classes for multimedia functionality.

    \generatelist{classesbymodule Phonon}

    ...
*/

지정된 모듈에 속하는 각 클래스는 \inmodule\class 주석에 이 명령어로 표시되어야 합니다.

qmltypesbymodule

classesbymodule 인자와 유사하지만, 두 번째 인자로 지정된 QML 모듈의 QML 유형(QML 값 유형 제외)을 나열하는 데 사용됩니다.

qmlvaluetypesbymodule

qmltypesbymodule 인수와 유사하지만, 대신 QML 값 유형을 나열합니다.

functionindex

functionindex 인수는 문서화된 모든 멤버 함수의 전체 알파벳순 목록을 제공합니다. 일반적으로 다음과 같은 방식으로 Qt 함수 색인 페이지를 생성하는 데만 사용됩니다:

/*!
    \page functions.html
    \title All Functions
    \ingroup funclists

    \brief All documented Qt functions listed alphabetically with a
    link to where each one is declared.

    This is the list of all documented member functions and global
    functions in the Qt API. Each function has a link to the
    class or header file where it is declared and documented.

    \generatelist functionindex
*/

legalese

legalese 인수는 QDoc에 현재 문서화 프로젝트의 라이선스 목록을 생성하도록 지시합니다. 각 라이선스는 \legalese 명령을 사용하여 식별됩니다.

overviews

overviews 인수는 QDoc이 모든 \group 페이지의 내용을 연결하여 목록을 생성하도록 지시하는 데 사용됩니다. Qt는 다음과 같은 방식으로 이 인수를 사용하여 개요 페이지를 생성합니다:

/*!
    \page overviews.html

    \title All Overviews and HOWTOs

    \generatelist overviews
*/

attributions

attributions 인수는 QDoc이 문서에 출처 목록을 생성하도록 지시하는 데 사용됩니다.

related

related 인수는 \group 및 \ingroup 명령과 함께 사용되어 지정된 그룹과 관련된 모든 개요를 나열합니다. 예를 들어, 'Qt를 이용한 프로그래밍' 페이지는 다음과 같은 방식으로 생성됩니다:

/*!
    \group qt-basic-concepts
    \title Programming with Qt

    \brief The basic architecture of the Qt cross-platform application and UI framework.

    Qt is a cross-platform application and UI framework for
    writing web-enabled applications for desktop, mobile, and
    embedded operating systems. This page contains links to
    articles and overviews explaining key components and
    techniuqes used in Qt development.

    \generatelist {related}
*/

이 그룹 페이지에 나열된 각 페이지에는 다음 명령이 포함되어 있습니다:

\ingroup qt-basic-concepts

참조 \annotatedlist.

\if

\if 명령어와 이에 대응하는 \endif 명령어는, 명령어의 인자로 지정된 조건이 참일 때만 포함될 QDoc 주석의 일부를 묶어줍니다.

이 명령어는 해당 줄의 나머지 부분을 읽어와 C++ #if 문으로 파싱합니다.

/*!
   \if defined(opensourceedition)

   \note This edition is for the development of
   \l{Qt Open Source Edition} {Free and Open Source}
   software only; see \l{Qt Commercial Editions}.

   \endif
*/

이 QDoc 주석은 opensourceedition 전처리기 심볼이 정의되어 있고, QDoc이 #ifdef 및 #endif 내의 코드를 처리하도록 구성 파일의 defines 변수에 지정된 경우에만 렌더링됩니다:

defines = opensourceedition

명령줄에서 이 전처리기 심볼을 수동으로 정의할 수도 있습니다. 자세한 내용은 defines 변수에 대한 문서를 참조하십시오.

참조 \endif, \else, defines 및 falsehoods.

\endif

\endif 명령어와 이에 대응하는 \if 명령어는 QDoc 주석의 일부를 묶어두며, \if 명령의 인수로 지정된 조건이 참일 때 포함될 QDoc 주석의 일부를 묶어줍니다.

자세한 내용은 \if 명령어의 문서를 참조하십시오.

다음 항목도 참조하십시오 \if, \else, 정의 및 허위 진술.

\else

\else 명령어는 \if 명령의 조건이 거짓일 때의 대안을 지정합니다.

\else 명령어는 \if...\endif 명령어 내에서만 사용할 수 있지만, 대안이 두 가지뿐인 경우에 유용합니다.

\include

\include 명령어는 첫 번째 인자로 지정된 파일의 전체 또는 일부를 QDoc 입력 스트림으로 전송하여 QDoc 주석 스니펫으로 처리되도록 합니다.

이 명령어는 명령어나 텍스트의 일부 스니펫을 문서의 여러 곳에서 사용해야 할 때 유용합니다. 문서에 스니펫을 삽입하고자 하는 곳이면 어디에서나 \include 명령어를 사용하십시오. 포함할 스니펫이 들어 있는 파일은 QDoc 구성 변수인 sourcedirs 또는 exampledirs에 나열된 경로 아래에 위치해야 합니다. 이 파일은 QDoc이 파싱하는 소스 파일( \include 명령어가 사용된 파일과 동일한 파일도 포함)이거나, 그 외의 텍스트 파일일 수 있습니다. QDoc이 파싱하지 않는 별도의 파일에 스니펫을 저장하려면 sources.fileextensions에 나열되지 않은 파일 확장자를 사용하십시오. 예를 들어, .qdocinc과 같은 확장자를 사용할 수 있습니다.

이 명령어에는 하나 이상의 인수가 있을 수 있습니다. 첫 번째 인수는 항상 파일 이름입니다. 파일의 내용은 QDoc 입력 형식, 즉 QDoc 명령어와 텍스트의 순서여야 하지만, QDoc 주석 구분자 /*! ... */ 는 포함되어서는 안 됩니다. 지정된 파일 전체를 포함하려면 두 번째 인수를 비워 두십시오. 파일의 일부만 포함하려면 아래의 두 번째 인자 형식을 참조하십시오. 다음은 하나의 인자 형식을 사용한 예시입니다:

/*!
    \page corefeatures.html
    \title Core Features

    \include examples/signalandslots.qdocinc
    \include examples/objectmodel.qdocinc
    \include examples/layoutmanagement.qdocinc
*/

\include 파일명 스니펫 식별자

문서 내 여러 곳에서 사용하고자 하는 QDoc 포함 스니펫마다 별도의 ` .qdocinc ` 파일을 만드는 것은 시간 낭비입니다. 특히 이러한 파일마다 저작권/라이선스 고지를 포함시켜야 할 가능성이 높다는 점을 고려하면 더욱 그렇습니다. 포함할 스니펫이 여러 개 있다면, 이 모든 것을 하나의 파일에 넣고 각 스니펫을 다음과 같이 감싸면 됩니다:

//! [snippet-id1]

QDoc commands and text...

//! [snippet-id1]

//! [snippet-id2]

More QDoc commands and text...

//! [snippet-id2]

그런 다음 다음 명령의 두 인자 형식을 사용할 수 있습니다:

\include examples/signalandslots.qdocinc snippet-id2
\include examples/objectmodel.qdocinc another-snippet-id

두 번째 인자와 동일한 이름을 가진 두 태그 사이에 있는 QDoc 명령어와 텍스트 시퀀스가 QDoc 입력 스트림으로 전송됩니다. 중첩된 스니펫을 사용할 수도 있습니다.

추가 인자

QDoc 6.3부터 \include 명령어에 전달된 추가 인수는 포함된 콘텐츠에 문자열을 삽입하는 데 사용됩니다. 콘텐츠의 특정 위치에 문자열을 삽입하려면 백슬래시 뒤에 숫자(1~9)를 추가하십시오. 이 숫자는 인수 목록의 순서와 일치합니다. QDoc이 공백 문자를 포함하여 인수를 예상한 대로 전체적으로 렌더링하도록 하려면 인수를 중괄호로 묶으십시오.

예를 들어, includes.qdocinc 파일에 다음 스니펫이 있다고 가정해 보겠습니다:

//! [usage]
To enable \e{\1}, select \uicontrol {\2} > \uicontrol Enable.
//! [usage]

이때, 다음 \include 줄은:

\include includes.qdocinc {usage} {detailed output} {Verbose}

다음과 같이 렌더링됩니다.

상세한 출력을 활성화하려면 ‘ Verbose ’ > ‘ Enable ’를 선택하십시오.

\meta

\meta 명령어는 문서에 메타데이터를 추가하는 데 사용됩니다. 이 명령어에는 두 개의 인수가 있습니다. 첫 번째 인수는 메타데이터 속성의 이름이고, 두 번째 인수는 해당 속성의 값입니다. 각 인수는 다음 예시와 같이 중괄호로 묶어야 합니다:

/*!
    \example demos/coffee
    \title Coffee Machine
    \brief A Qt Quick application with a state-based custom user interface.

    \meta {tags} {quick,embedded,states,touch}
    \meta {category} {Application Examples}
*/

여러 메타데이터 속성은 각각 특정 용도를 가지고 있습니다:

메타데이터 예시

\meta 명령어의 또 다른 용도는 메타데이터(태그)를 \example 문서에 메타데이터(태그)를 포함시키는 것입니다. 기본적으로 QDoc은 예제의 \title 및 모듈 이름을 기반으로 예제 태그를 생성합니다. 이러한 태그는 Qt Creator 의 ‘Welcome’ 모드에 표시되어 사용자가 예제 목록을 탐색하는 데 도움을 줍니다.

\meta {tag} {tag1} 또는 \meta {tags} {tag1,[tag2,...]} 을 사용하여 추가 태그를 생성할 수 있습니다. 예를 들어:

/*!
    \example helloworld
    \title Hello World Example
    \meta {tags} {tutorial,basic}
*/

이렇게 하면 tutorial, basic, hello, world와 같은 태그가 생성됩니다. example과 같은 일반적인 단어는 무시됩니다.

예제 제외하기

예제를 '작동하지 않음'으로 표시하면 생성된 매니페스트 파일에서 해당 예제가 제외되며, 결과적으로 Qt Creator 의 'Welcome' 모드에서 해당 예제가 제거됩니다.

\meta {tag} {broken}

예제 설치 경로

' installpath ' 인수를 함께 사용하는 \meta 명령어는 설치된 예제의 위치를 지정합니다. 이 값은 examplesinstallpath 구성 변수를 통해 설정된 값을 재정의합니다.

/*!
    \example helloworld
    \title Hello World Example
    \meta {installpath} {tutorials}
*/

examplesinstallpath 항목도 참조하십시오.

상태

\meta 명령에 대한 ` status ` 인수는 \class 또는 \qmltype에 대한 사용자 정의 상태 설명을 추가합니다. 이 설명은 이후 해당 유형 참조 페이지 상단의 표에 표시됩니다.

/*!
    \class QNativeInterface::QAndroidApplication
    \meta {status} {Android-specific}
*/

상태 관련 명령어 항목도 참조하십시오.

문서 메타데이터

\meta 명령어의 ` keywords ` 인수는 지정된 키워드를 생성된 문서의 메타데이터로 추가합니다:

\meta {keywords} {reference, internal}

HTML 출력에서 이러한 키워드는 ` <meta name="keywords" content="..."> ` 요소로 생성됩니다.

\noautolist

\noautolist 명령어는 C++ 또는 QML 모듈 페이지 하단에 자동으로 생성되는 주석이 달린 C++ 클래스 또는 QML 유형 목록을 생략해야 함을 나타냅니다. 이는 해당 클래스나 유형이 수동으로 나열되었기 때문입니다. 이 명령어는 \group 명령과 함께 사용하여, 그룹 구성원이 수동으로 나열된 경우 해당 목록을 생략할 수 있습니다.

이 명령어는 반드시 별도의 줄에 작성해야 합니다. 예시는 Qt Quick Controls QML Types 를 참조하십시오. 이 페이지는 qtquickcontrols2-qmlmodule.qdoc 에서 생성되었습니다. 해당 페이지에는 QtQuick.Controls 모듈에 대한 \qmlmodule 명령어가 포함된 QDoc 주석이 있습니다. 같은 주석에는 자동 목록 생성을 비활성화하는 \noautolist 명령어와, 문서의 특정 섹션에 QML 유형을 나열하기 위한 \generatelist 문서의 특정 섹션에 있는 QML 유형을 나열하는 명령도 포함되어 있습니다.

이 명령어는 QDoc 5.6에서 도입되었습니다.

Qt 5.10부터는 이 명령을 \example 문서에도 적용할 수 있으며, 이 경우 예제 프로젝트에 속한 파일 및 이미지의 자동 생성 목록이 생략됩니다.

\omit

\omit 명령어와 이에 대응하는 \endomit 명령어는 QDoc이 건너뛰도록 할 문서 부분을 지정합니다. 예를 들어:

/*!
    \table
    \row
        \li Basic Widgets
        \li Basic GUI widgets such as buttons, comboboxes
           and scrollbars.

    \omit
    \row
        \li Component Model
        \li Interfaces and helper classes for the Qt
           Component Model.
    \endomit

    \row
        \li Database Classes
        \li Database related classes, e.g. for SQL databases.
    \endtable
*/

\raw (피해야 함!)

\raw 명령어와 이에 대응하는 \endraw 명령어는 원시 마크업 언어 코드 블록의 경계를 지정합니다.

이 명령어는 코드의 형식을 지정하는 인수를 받습니다.

QDoc은 사용자가 지정한 형식을 생성할 때만 주어진 코드를 생성합니다.

예를 들어, “\raw HTML”은 QDoc이 HTML 문서를 생성할 때만 코드를 생성합니다.

\sincelist

\sincelist 명령어는 지정된 버전의 문서화된 API에 새로 추가된 항목을 상세하게 나열합니다. 사용 예:

/*!
   \page newclasses612.html
   \title New Classes and Functions in 6.12
   \brief A comprehensive list of new classes and functions in 6.12.

   \sincelist 6.12
*/

\sincelist이 명령어는 버전 문자열이라는 단일 인수를 받습니다. 생성된 출력에는 버전 문자열과 일치하는 \since command 또는 since 절로 표시된 모든 기능을 포함합니다.

\unicode

\unicode 명령어를 사용하면 문서에 임의의 유니코드 문자를 삽입할 수 있습니다.

이 명령어는 정수로 문자를 지정하는 인수를 받습니다. '0x' 또는 '0' 접두사가 지정되지 않은 경우(각각 16진수 및 8진수를 나타냄), 기본적으로 10진수가 가정됩니다.