주제별 명령어

주제 명령어는 QDoc에 어떤 소스 코드 요소에 대한 문서를 작성 중인지 알려줍니다. 일부 주제 명령어를 사용하면 기본이 되는 소스 코드 요소와 연결되지 않은 문서 페이지를 생성할 수도 있습니다.

QDoc이 QDoc 주석을 처리할 때, 먼저 해당 소스 코드 요소의 이름을 지정하는 토픽 명령어를 찾아 주석을 소스 코드 내의 요소와 연결하려고 시도합니다. 토픽 명령어가 없는 경우, QDoc은 주석 바로 뒤에 오는 소스 코드 요소와 주석을 연결하려고 시도합니다. 이 두 가지 방법 모두 불가능하고, 주석에 기본이 되는 소스 코드 요소가 없음을 나타내는 주제 명령어(예: \page)도 없다면, 해당 주석은 무시됩니다.

문서화 대상 엔티티의 이름은 대개 topic 명령의 유일한 인자입니다. 전체 이름을 사용하십시오. 경우에 따라 인자에 두 번째 매개변수가 포함될 수 있습니다. 예를 들어 \page를 참조하십시오.

\enum QComboBox::InsertPolicy

\fn 명령어는 특수한 경우입니다. \fn 명령어의 경우, 클래스 한정자를 포함한 함수의 시그니처를 사용하십시오.

\fn void QGraphicsWidget::setWindowFlags(Qt::WindowFlags wFlags)

토픽 명령어는 주석 내 어디에나 나타날 수 있지만, 반드시 별도의 줄에 단독으로 위치해야 합니다. 토픽 명령어를 주석의 첫 번째 줄에 배치하는 것이 좋은 관행입니다. 인수가 여러 줄에 걸쳐 있는 경우, 마지막 줄을 제외한 각 줄의 끝에는 백슬래시를 반드시 붙여야 합니다. 또한, QDoc은 괄호를 카운트하므로, '('를 만나면 닫는 괄호 ')'까지의 모든 내용을 인수로 간주합니다.

주제 명령어가 서로 다른 인수로 반복될 경우, 두 유닛 모두에 대해 동일한 문서가 표시됩니다.

/*!
    \fn void PreviewWindow::setWindowFlags()
    \fn void ControllerWindow::setWindowFlags()

    Sets the widgets flags using the QWidget::setWindowFlags()
    function.

    Then runs through the available window flags, creating a text
    that contains the names of the flags that matches the flags
    parameter, displaying the text in the widgets text editor.
*/

PreviewWindow::setWindowFlags() 와 ControllerWindow::setWindowFlags() 함수는 동일한 설명문을 갖게 됩니다.

주제 명령어로 생성된 파일의 명명 규칙

다음과 같은 많은 topic 명령어의 경우 \page와 같은 많은 topic 명령어의 경우, QDoc은 문서를 처리할 때 파일을 생성합니다.

QDoc은 각 파일의 이름을 정규화한 후 디스크에 기록합니다. 이때 다음과 같은 작업이 수행됩니다:

• 영숫자가 아닌 모든 문자열은 하이픈('-')으로 대체됩니다.
• 모든 대문자는 소문자로 대체됩니다.
• 문자열 끝의 하이픈은 모두 제거됩니다.

예를 들어, 다음 명령어는 this-generates-a-file-and-writes-it-to-disk.html 라는 이름의 파일을 생성합니다:

\page this_generates_a_file_(and_writes_it_to_DISK)-.html

예시에서 볼 수 있듯이, 명령어에서 지정한 파일 이름은 디스크에 실제로 기록되는 파일 이름과 다를 수 있습니다.

생성된 파일의 접두사 및 접미사

QDoc이 파일을 생성할 때, 해당 파일이 설명할 요소에 따라 접두사, 접미사 또는 둘 다를 추가할 수 있습니다.

아래 표는 다양한 요소에 대해 이러한 접두사와 접미사가 어떻게 적용되는지 보여줍니다.

\class

\class 명령어는 C++ 클래스, C/C++ 구조체 또는 유니온을 문서화하는 데 사용됩니다. 인수는 클래스의 완전한 정규화된 이름입니다. 이 명령어는 QDoc에 해당 클래스가 공개 API의 일부임을 알리고, 사용자가 자세한 설명을 입력할 수 있게 해줍니다.

/*!
    \class QMap::iterator
    \inmodule QtCore

    \brief The QMap::iterator class provides an STL-style
    non-const iterator for QMap and QMultiMap.

    QMap features both \l{STL-style iterators} and
    \l{Java-style iterators}. The STL-style iterators ...
*/

지정된 클래스에 대한 HTML 문서는 클래스 이름을 소문자로 표기하고, 이중 콜론(::) 구분자를 '-'로 대체한 이름의 .html 파일에 작성됩니다. 예를 들어, ` QMap::iterator ` 클래스에 대한 문서는 ` qmap-iterator.html` 파일에 작성됩니다.

이 파일에는 \class 주석에 포함된 클래스 설명과 더불어, 모든 클래스 멤버에 대한 QDoc 주석에서 생성된 문서, 즉 클래스의 타입, 속성, 함수, 신호 및 슬롯 목록이 포함됩니다.

클래스에 대한 상세한 설명 외에도, \class 주석에는 일반적으로 \inmodule 명령어와 \brief 설명도 포함합니다. 다음은 매우 간단한 예시입니다:

/*!
    \class PreviewWindow
    \inmodule CustomWidgets
    \brief The PreviewWindow class is a custom widget.
           displaying the names of its currently set
           window flags in a read-only text editor.

    \ingroup miscellaneous

    The PreviewWindow class inherits QWidget. The widget
    displays the names of its window flags set with the \l
    {function} {setWindowFlags()} function. It is also
    provided with a QPushButton that closes the window.

    ...

    \sa QWidget
*/

QDoc이 이 \class 를 어떻게 렌더링할지는 사용자의 ` style.css ` 파일에 따라 달라집니다.

\concept

\concept 명령어는 C++20 컨셉트마다 별도의 페이지를 생성하고, 템플릿 제약 조건에서 해당 컨셉트를 참조하는 문서화된 유형 및 함수를 모아 보여줍니다. 인수는 컨셉트의 완전 한정된 이름이며, 이는 Clang이 선언에 대해 보고하는 이름과 일치해야 합니다. 파일 범위 내의 컨셉트는 이름만 사용하면 되지만, 네임스페이스 내의 컨셉트는 algorithms::Ordered 과 같이 완전 한정된 이름을 사용해야 합니다.

유형이나 함수는 개념의 페이지에 자동으로 추가됩니다. QDoc이 문서화된 선언을 파싱할 때, 해당 선언의 제약 조건을 검사하고 참조하는 개념에 해당 선언을 등록합니다. 제약 조건이 적용된 항목 자체에 대해 \ingroup 또는 \inmodule 형식의 명령어를 실행할 필요는 없습니다.

QDoc은 C++20 제약 조건의 다음 세 가지 구문 형식을 인식합니다:

• 명시적인 requires 절로, 템플릿 헤더(template <typename T> requires Ordered<T>)에 나타나든 함수 시그니처 뒤에 나타나든 상관없습니다.
• 제약이 적용된 auto 매개변수(void sort(Ordered auto& range)).
• 템플릿 매개변수에 직접 지정된 컨셉(template <Ordered T> class SortedSet).

\concept 명령어 뒤에는 일반적으로 \inmodule 명령어와 \brief 설명이 이어집니다. 주석의 본문은 상세한 설명으로 표시되며, \section1 제목은 다른 문서 페이지에서와 마찬가지로 작동합니다.

/*!
    \concept Ordered
    \inmodule Algorithms

    \brief A type that admits a total order.

    The Ordered concept is satisfied by any type that supplies the
    relational operators \c {<}, \c {<=}, \c {>}, and \c {>=}, and for
    which those operators induce a strict total order.

    \section1 Definition

    Ordered evaluates to \c true when \c {T} is totally ordered
    and to \c false otherwise.
*/

QDoc은 해당 개념에 대한 참조 페이지를 생성합니다. 위의 예시의 경우, 해당 페이지는 ordered.html 이며, 여기에는 개요, 상세 설명, 그리고 생성된 문서에 포함된 문서화된 유형 및 함수 중 제약 조건이 Ordered 를 참조하는 항목들을 나열한 ‘사용처(Used by) ’ 섹션이 포함되어 있습니다. 각 항목은 링크로 표시되며, 그 뒤에는 해당 항목의 문서에서 가져온 \brief 설명이 이어지며, 이는 \group 및 \module 페이지의 목록과 동일한 형식을 따릅니다.

표준 라이브러리에 포함된 개념과 같이 문서화되지 않은 개념에 대한 참조는 아무런 메시지 없이 무시됩니다. 이러한 참조는 페이지를 생성하지 않으며 경고도 표시하지 않습니다.

참조 \group, \module, 및 \inmodule.

\enum

\enum 명령어는 C++ 열거형(enum) 유형을 문서화하기 위한 것입니다. 인수는 열거형 유형의 전체 이름입니다.

열거형 값들은 \enum 주석 내에서 \value 명령을 사용하여 문서화됩니다. 열거형 값이 ` \value` 명령으로 문서화되지 않은 경우, QDoc은 경고를 표시합니다. 이러한 경고는 \omitvalue 명령을 사용하여 해당 열거형 값에 대한 문서를 작성하지 말아야 함을 QDoc에 알릴 수 있습니다. 열거형 문서는 해당 열거형 유형이 정의된 클래스 참조 페이지, 헤더 파일 페이지 또는 네임스페이스 페이지에 포함됩니다. 예를 들어, Qt 네임스페이스에 있는 Corner 열거형 유형을 살펴보겠습니다:

enum Corner {
    TopLeftCorner = 0x00000,
    TopRightCorner = 0x00001,
    BottomLeftCorner = 0x00002,
    BottomRightCorner = 0x00003
#if defined(QT3_SUPPORT) && !defined(Q_MOC_RUN)
    ,TopLeft = TopLeftCorner,
    TopRight = TopRightCorner,
    BottomLeft = BottomLeftCorner,
    BottomRight = BottomRightCorner
#endif
};

이 열거형에 대한 문서는 다음과 같이 작성할 수 있습니다:

/*!
    \enum Qt::Corner

    This enum type specifies a corner in a rectangle:

    \value TopLeftCorner
           The top-left corner of the rectangle.
    \value TopRightCorner
           The top-right corner of the rectangle.
    \value BottomLeftCorner
           The bottom-left corner of the rectangle.
    \value BottomRightCorner
           The bottom-right corner of the rectangle.

    \omitvalue TopLeft
    \omitvalue TopRight
    \omitvalue BottomLeft
    \omitvalue BottomRight
               Bottom-right (omitted; not documented).
*/

네임스페이스 한정자가 포함되어 있다는 점에 유의하십시오.

참조: \value 및 \omitvalue.

\example

\example 명령어는 예제를 문서화하기 위한 것입니다. 인수는 QDoc 구성 파일의 exampledirs 변수에 나열된 경로 중 하나를 기준으로 한 예제의 상대 경로입니다.

문서화 페이지는 modulename-path-to-example.html에 출력됩니다. QDoc은 페이지 하단에 예제의 모든 소스 파일 및 이미지 파일 목록을 추가합니다. 단, \noautolist command가 사용되거나 프로젝트에 대해 구성 변수 url.examples가 정의된 경우는 예외입니다.

예를 들어, exampledirs에 $QTDIR/examples/widgets/imageviewer 이 포함되어 있다면,

/*!
    \example widgets/imageviewer
    \title ImageViewer Example
    \subtitle

    The example shows how to combine QLabel and QScrollArea
    to display an image.

    ...
*/

참조: \noautolist, url.examples, \meta

\externalpage

\externalpage 명령어는 외부 URL에 제목을 지정합니다.

/*!
    \externalpage https://doc.qt.io/
    \title Qt Documentation Site
*/

이를 통해 다음과 같은 방식으로 문서에 외부 페이지로 연결되는 링크를 삽입할 수 있습니다:

/*!
    At the \l {Qt Documentation Site} you can find the latest
    documentation for Qt, Qt Creator, the Qt SDK and much more.
*/

\externalpage 명령어를 사용하지 않고 동일한 결과를 얻으려면, 문서 내에 주소를 직접 하드코딩해야 합니다:

/*!
    At the \l {http://doc.qt.io/}{Qt Documentation Site}
    you can find the latest documentation for Qt, Qt Creator, the Qt SDK
    and much more.
*/

\externalpage 명령어를 사용하면 문서 유지 관리가 더 쉬워집니다. 주소가 변경되더라도 \externalpage 명령어의 인자만 변경하면 됩니다.

\fn (함수)

\fn 명령어는 함수를 문서화하는 데 사용됩니다. 인수는 템플릿 매개변수(있는 경우), 반환 유형, const 여부, 유형이 지정된 형식 매개변수 목록을 포함한 함수의 시그니처입니다. 지정한 함수가 존재하지 않으면 QDoc은 경고를 표시합니다.

이 명령어는 QDoc이 전체 타입을 추론할 수 있더라도 함수의 타입으로 ` auto `을 허용합니다. 특정 상황에서는 함수의 실제 타입 대신 `auto`를 사용하는 것이 더 바람직할 수 있습니다. ` \fn` 명령어에서 반환 타입으로 ` auto `을 사용하면, 작성자는 ` auto ` 키워드 없이 정의된 타입에 대해서도 이를 명시적으로 지정할 수 있습니다.

QDoc 버전 6.0부터는 ` \fn ` 명령어를 사용하여 헤더에 명시적으로 선언되지 않았지만 컴파일러에 의해 암시적으로 생성된 클래스 멤버(기본 생성자 및 소멸자, 복사 생성자 및 이동 복사 생성자, 할당 연산자, 이동 할당 연산자)를 문서화할 수 있습니다.

숨겨진 프렌드(hidden friend)를 문서화할 때는 클래스 한정 구문이나 한정되지 않은 자유 함수 구문을 모두 사용할 수 있습니다. 예를 들어, 다음과 같은 경우:

class Foo {
   ...
   friend bool operator==(const Foo&, const Foo&) { ... }
   ...
}

이 명령어는 ` "\fn Foo::operator==(const Foo&, const Foo&)" ` 또는 자유 함수 형식인 ` "\fn bool operator==(const Foo&, const Foo&)"`으로 작성할 수 있습니다. QDoc은 함수의 매개변수 유형에서 참조되는 클래스를 검색하여 숨겨진 프렌드를 해결합니다.

/*!
    \fn bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const

    Returns \c true if this toolbar is dockable in the given
    \a area; otherwise returns \c false.
*/

참조 \overload.

\group

\group 명령어는 지정된 그룹에 속한 클래스, 페이지 또는 기타 개체를 나열하는 별도의 페이지를 생성합니다. 인수는 그룹 이름입니다.

클래스는 \ingroup 명령을 사용하여 클래스를 그룹에 포함시킵니다. 개요 페이지도 동일한 명령을 사용하여 그룹과 연결할 수 있지만, 개요 페이지 목록은 \generatelist 명령을 통해 명시적으로 요청해야 합니다(아래 예시 참조).

\group 명령어 뒤에는 일반적으로 \title 명령어와 그룹에 대한 간단한 소개가 이어집니다. 그룹에 대한 HTML 페이지는 <소문자 그룹 이름>.html이라는 이름의 .html 파일에 기록됩니다.

그룹에 속한 각 엔티티는 (페이지 제목이나 클래스 이름을 사용하여) 링크 형태로 나열되며, 그 뒤에는 해당 엔티티의 설명서에서 가져온 \brief 명령어에 대한 설명이 이어집니다.

/*!
    \group io
    \title Input/Output and Networking
*/

QDoc은 그룹 페이지 io.html 를 생성합니다.

해당 그룹과 관련된 개요 페이지는 \generatelist 명령어와 related 인수를 사용하여 명시적으로 나열해야 한다는 점에 유의하십시오.

/*!
    \group architecture

    \title Architecture

    These documents describe aspects of Qt's architecture
    and design, including overviews of core Qt features and
    technologies.

    \generatelist{related}
*/

참조: \ingroup, \annotatedlist, \generatelist, 그리고 \noautolist.

\headerfile

\headerfile 명령어는 헤더 파일에 선언되었으나 네임스페이스에는 선언되지 않은 전역 함수, 유형 및 매크로를 문서화하기 위한 것입니다. 인수는 헤더 파일의 이름입니다. HTML 페이지는 헤더 파일 인수로 생성된 .html 파일에 기록됩니다.

문서화 대상 헤더 파일에 선언된 함수, 타입 또는 매크로에 대한 설명은 \relates 명령을 사용하여 해당 헤더 파일 페이지에 포함됩니다.

인수가 헤더 파일로 존재하지 않더라도, ` \headerfile ` 명령어는 해당 헤더 파일에 대한 문서 페이지를 생성합니다.

/*!
   \headerfile <QtAlgorithms>

   \title Generic Algorithms

   \brief The <QtAlgorithms> header file provides
    generic template-based algorithms.

   Qt provides a number of global template functions in \c
   <QtAlgorithms> that work on containers and perform
   well-know algorithms.
*/

QDoc은 헤더 파일 페이지인 qtalgorithms.html 를 생성합니다.

참조: \inheaderfile.

\macro

\macro 명령어는 C++ 매크로를 문서화하기 위한 것입니다. 인수는 다음 세 가지 형식 중 하나로 된 매크로입니다: Q_ASSERT()와 같은 함수형 매크로, Q_PROPERTY()와 같은 선언형 매크로, 그리고 Q_OBJECT 와 같이 괄호가 없는 매크로입니다.

\macro 주석에는 \relates 매크로 주석을 클래스, 헤더 파일 또는 네임스페이스에 연결하는 명령을 반드시 포함해야 합니다. 그렇지 않으면 문서가 손실됩니다.

\module

\module 는 명령어의 인자로 지정된 모듈에 속하는 클래스들을 나열하는 페이지를 생성합니다. 주석 내에 \inmodule\class 명령을 통해 모듈에 포함된 클래스도 해당 모듈에 속합니다.

\module 명령어 뒤에는 일반적으로 \title 및 \brief 명령어가 이어집니다. 각 클래스는 클래스 참조 페이지로 연결되는 링크로 나열되며, 그 뒤에는 해당 클래스의 \brief 명령의 텍스트가 이어집니다. 예를 들어:

/*!
    \module QtNetwork

    \title Qt Network Module

    \brief Contains classes for writing TCP/IP clients and servers.

    The network module provides classes to make network
    programming easier and portable. It offers both
    high-level classes such as QNetworkAccessManager that
    implements application-level protocols, and
    lower-level classes such as QTcpSocket, QTcpServer, and
    QUdpSocket.
*/

이 \noautolist 명령을 사용하면 마지막에 자동으로 생성되는 클래스 목록을 생략할 수 있습니다.

참조: \inmodule

\namespace

\namespace 명령어는 인자로 지정된 이름의 C++ 네임스페이스 내용을 문서화하는 데 사용됩니다. QDoc이 네임스페이스에 대해 생성하는 참조 페이지는 C++ 클래스에 대해 생성하는 참조 페이지와 유사합니다.

/*!
    \namespace Qt

    \brief Contains miscellaneous identifiers used throughout the Qt library.
*/

C++에서는 특정 네임스페이스를 여러 모듈에서 사용할 수 있지만, 서로 다른 모듈의 C++ 요소가 동일한 네임스페이스에 선언된 경우 해당 네임스페이스 자체는 하나의 모듈에서만 문서화되어야 한다는 점에 유의하십시오. 예를 들어, 위 예제의 namespace Qt에는 QtCore 과 QtGui 모두의 유형과 함수가 포함되어 있지만, \namespace 명령어를 통해 QtCore 에서만 문서화됩니다.

\page

\page 명령어는 독립형 문서 페이지를 생성하기 위한 것입니다.

\page 명령어는 QDoc이 페이지를 저장할 파일 이름을 나타내는 단일 인수를 받습니다.

페이지 제목은 \title 명령을 사용하여 설정합니다.

/*!
   \page aboutqt.html

   \title About Qt

   Qt is a C++ toolkit for cross-platform GUI
   application development. Qt provides single-source
   portability across Microsoft Windows, macOS, Linux,
   and all major commercial Unix variants.

   Qt provides application developers with all the
   functionality needed to build applications with
   state-of-the-art graphical user interfaces. Qt is fully
   object-oriented, easily extensible, and allows true
   component programming.

   ...
*/

QDoc은 이 페이지를 aboutqt.html 에서 표시합니다.

\property

\property 명령어는 Qt 속성을 문서화하기 위한 것입니다. 인수는 전체 속성 이름입니다.

속성은 Q_PROPERTY() 매크로를 사용하여 정의됩니다. 이 매크로는 속성 이름과 set, reset, get 함수를 인수로 받습니다.

Q_PROPERTY(QString state READ state WRITE setState)

set, reset, get 함수는 별도로 문서화할 필요가 없으며, 속성만 문서화하면 충분합니다. QDoc은 속성 문서 내에 표시될 액세스 함수 목록을 생성하며, 이 문서는 해당 속성을 정의하는 클래스의 문서에서 확인할 수 있습니다.

\property 명령어의 주석에는 일반적으로 \brief 명령어를 포함합니다. 속성의 경우 \brief 명령어의 인수는 속성에 대한 한 줄 설명에 포함될 문장 일부입니다. 이 명령어는 설명에 있어 \variable 명령과 동일한 규칙을 따릅니다.

/*!
    \property QPushButton::flat
    \brief Whether the border is disabled.

    This property's default is false.
*/

\qmlattachedmethod

\qmlattachedmethod 명령어는 특정 QML 유형에 연결된 메서드(연결 속성)를 문서화하는 데 사용됩니다. \qmlattachedmethod 명령어는 \qmlmethod 명령과 똑같이 사용됩니다.

인수는 해당 줄의 나머지 부분이며, 반환 유형으로 시작하여 메서드가 선언된 QML 유형 이름, :: 한정자, 그리고 마지막으로 괄호 안에 매개변수 유형과 이름이 포함된 메서드 이름으로 구성된 완전한 메서드 시그니처여야 합니다. 메서드가 인수를 받지 않는 경우 () 를 사용하십시오.

예를 들어, ` ToolTip ` 유형에 대한 ` show() `이라는 부착 메서드를 문서화하려면 다음과 같이 합니다:

/*!
    \qmlattachedmethod void QtQuick.Controls::ToolTip::show(string text, int timeout = -1)

    This attached method shows the shared tool tip with \a text for
    \a timeout milliseconds. You can attach the method to any item.
*/

QDoc은 이 문서를 ToolTip 유형에 대한 QML 참조 페이지에 포함합니다.

\qmlattachedproperty

\qmlattachedproperty 명령어는 특정 QML 유형에 연결될 QML 속성을 문서화하기 위한 것입니다. ‘연결된 속성(Attached Properties)’을 참조하십시오. 인수는 해당 줄의 나머지 부분입니다. 인수는 속성 유형으로 시작해야 하며, 그 다음으로 속성이 선언된 QML 유형 이름, ‘ :: ’ 한정자, 마지막으로 속성 이름이 이어져야 합니다.

예를 들어, ` ListView ` 유형에 대한 ` isCurrentItem `이라는 부울형 QML 부착 속성을 문서화하려면:

/*!
    \qmlattachedproperty bool ListView::isCurrentItem

    This attached property is \c true if this delegate is the current
    item; otherwise false.

    It is attached to each instance of the delegate.

    This property may be used to adjust the appearance of the current
    item, for example:

    \snippet doc/src/snippets/declarative/listview/listview.qml isCurrentItem
*/

QDoc은 이 부착 속성을 ListView 유형의 QML 참조 페이지에 포함시킵니다.

\qmlattachedsignal

\qmlattachedsignal 명령어는 연결 가능한 신호를 문서화하는 데 사용됩니다. \qmlattachedsignal 명령어는 \qmlsignal 명령과 똑같이 사용됩니다.

인수는 해당 줄의 나머지 부분입니다. 여기에는 신호가 선언된 QML 유형의 이름, ` :: ` 한정자, 그리고 마지막으로 신호 이름이 포함되어야 합니다. 예를 들어, ` GridView ` 요소 내의 ` add() `이라는 이름의 QML 부착 신호는 다음과 같이 문서화됩니다:

/*!
    \qmlattachedsignal GridView::add()
    This attached signal is emitted immediately after an item is added to the view.
*/

QDoc은 이 문서를 GridView 요소의 QML 참조 페이지에 포함합니다.

\qmlvaluetype

\qmlvaluetype 명령어는 QML용 값 유형을 문서화하기 위한 것입니다. 이 명령어는 유형 이름을 유일한 인수로 받습니다.

\qmlvaluetype는 기능적으로 \qmltype 명령과 기능적으로 동일합니다. 유일한 차이점은 해당 타입이 QML 값 타입으로 제목이 지정되고(그리고 그룹화됨) 있다는 점입니다.

\qmlclass

이 명령어는 더 이상 권장되지 않습니다. 대신 \qmltype 를 대신 사용하십시오.

\qmlenum

\qmlenum 명령어는 QML 열거형을 문서화하기 위한 것입니다. 이 명령어는 단일 인수를 받으며, 이 인수는 상위 QML 유형을 포함하고 선택적으로 QML 모듈을 포함하는 열거형 유형의 전체 이름입니다.

열거자 및 해당 설명은 \value 명령을 사용하여 문서화됩니다.

예를 들어,

/*!
    \qmlenum My.Module::Color::Channel
    \brief Specifies a color channel in the RGB colorspace.

    \value R
           Red color channel

    \value G
           Green color channel

    \value B
           Blue color channel
*/

이렇게 하면 Color.R, Color.G, Color.B라는 세 개의 열거자가 있는 열거형 Channel에 대한 문서가 생성됩니다. 기본적으로 상위 QML 유형 이름이 열거자의 접두사로 사용됩니다.

qdoccmd{value} 명령의 첫 번째 인자에 이미 접두사가 포함되어 있는 경우, 해당 접두사는 있는 그대로 사용됩니다:

\value Channel.R
       Red color channel
\value Channel.G
       Green color channel
\value Channel.B
       Blue color channel

여기서 열거자는 Channel.R, Channel.G, Channel.B로 나열됩니다.

또는 기존 C++ \enum 주제의 설명서를 복제할 수 있습니다. \qmlenumeratorsfrom 명령을 사용하여 기존 C++주제의 열거자 문서를 복제할 수도 있습니다.

이 명령어는 Qt 6.10에서 도입되었습니다.

참조: \qmlenumeratorsfrom.

\qmlmethod

\qmlmethod 명령어는 QML 메서드를 문서화하기 위한 것입니다. 인수는 완전한 메서드 시그니처이며, 반환 유형과 괄호로 묶인 매개변수 이름 및 유형을 반드시 포함해야 합니다. 메서드가 인수를 받지 않는 경우, () 를 사용하십시오.

/*!
    \qmlmethod void TextInput::select(int start, int end)

    Causes the text from \a start to \a end to be selected.

    If either start or end is out of range, the selection is not changed.

    After having called this, selectionStart will become the lesser, and
    selectionEnd the greater (regardless of the order passed to this method).

   \sa selectionStart, selectionEnd
*/

QDoc은 이 문서를 TextInput 유형의 유형 참조 페이지에 포함합니다.

\qmltype

\qmltype 명령어는 QML 타입에 대한 문서를 작성하는 데 사용됩니다. 이 명령어에는 QML 타입의 이름을 나타내는 하나의 인수가 있습니다.

QML 유형에 상응하는 C++ 클래스가 있는 경우, \nativetype context 명령어를 사용하여 해당 클래스를 지정할 수 있습니다.

xml-ph-0000@deepl.internal \inqmlmodule 명령어는 해당 타입이 속한 QML 모듈에 대한 정보를 제공합니다. 이 명령어에 전달되는 인수는 문서화된 \qmlmodule 페이지와 일치해야 합니다.

/*!
    \qmltype Transform
    \nativetype QGraphicsTransform
    \inqmlmodule QtQuick

    \brief Provides a way to build advanced transformations on Items.

    The Transform element is a base type which cannot be
    instantiated directly.
*/

여기서 \qmltype 주석에는 \nativetype Transform이 C++ 클래스 ` QGraphicsTransform`의 QML 대응체임을 명시하고 있습니다. ` \qmltype ` 주석에는 항상 \since 명령을 포함해야 합니다. 또한 \brief 설명도 포함되어야 합니다. QML 유형이 QML 유형 그룹의 구성원인 경우, ` \qmltype ` 주석에는 하나 이상의 \ingroup 명령어를 하나 이상 포함해야 합니다.

\qmlsingletontype

\qmlsingletontype 명령어는 QML 싱글톤 유형을 명시적으로 문서화하기 위한 것입니다. 이 명령어는 기능적으로 \qmltype와 기능적으로 동일하지만, C++ 구현 방식과 관계없이 해당 타입을 명시적으로 싱글톤으로 표시합니다.

QML 싱글톤 유형은 QML 엔진 내에 단 하나의 인스턴스만 존재하도록 보장합니다. 싱글톤으로 지정된 사실은 생성된 문서에서 제목에 "(Singleton)" 표시와 함께 설명 문구로 표시됩니다.

/*!
    \qmlsingletontype Settings
    \inqmlmodule MyApp

    \brief Provides application-wide settings as a singleton.

    The Settings type is a singleton that maintains application
    configuration. Access it directly without instantiation.
*/

QML_SINGLETON 매크로를 사용하는 C++ 클래스의 경우, \qmltype 를 사용하는 것이 좋습니다. QDoc이 C++ 코드에서 싱글톤 특성을 자동으로 감지하기 때문입니다.

참조: \qmluncreatabletype.

\qmluncreatabletype

\qmluncreatabletype 명령어는 QML 유형 시스템에 등록되어 있지만 QML에서 직접 인스턴스화할 수 없는 유형을 명시적으로 문서화하기 위한 것입니다.

이 명령은 기능적으로 \qmltype와 기능적으로 동일하지만, C++ 구현과 관계없이 해당 타입을 생성 불가능한 것으로 명시적으로 표시합니다.

생성 불가능한 유형으로 지정된 경우, 생성된 문서에서는 제목에 "(생성 불가능)" 표시와 함께 설명 문구가 표시됩니다.

/*!
    \qmluncreatabletype Dialog
    \inqmlmodule QtQuick.Dialogs

    \brief The base type of native dialogs.
*/

QML_UNCREATABLE 매크로를 사용하는 C++ 클래스의 경우, \qmltype 를 사용하는 것이 좋습니다. QDoc이 C++ 코드에서 생성 불가능한 특성을 자동으로 감지하기 때문입니다.

\qmluncreatabletype 명령어는 Qt 6.12에서 QDoc에 도입되었습니다.

참조: \qmlsingletontype.

\qmlproperty

\qmlproperty 명령어는 QML 속성을 문서화하기 위한 것입니다. 인수는 해당 줄의 나머지 부분입니다. 인수 텍스트는 속성 유형, 그 뒤에 QML 유형 이름, :: 한정자, 그리고 마지막으로 속성 이름 순으로 구성되어야 합니다. QML 유형 Translate 에 x 라는 QML 속성이 있고, 해당 속성의 유형이 real 인 경우, 이에 대한 \qmlproperty 는 다음과 같이 표시됩니다:

/*!
    \qmlproperty real Translate::x

    The translation along the X axis.
*/

QDoc은 이 QML 속성을 Translate 유형의 QML 참조 페이지에 포함합니다.

\default 명령어는 속성의 기본값을 문서화하는 데 사용됩니다:

\qmlproperty real AxisHelper::gridOpacity
\default 0.5

QML 속성이 C++ 열거형을 노출하는 경우, 해당 QML 속성은 ` enumeration` 유형으로 정의됩니다:

\qmlproperty enumeration ParticleShape3D::ShapeType

열거형 타입을 갖는 속성과 플래그의 비트 단위 조합을 포함하는 속성은 \value 명령을 사용하여 허용되는 값을 문서화할 수 있습니다.

\qmlproperty enumeration Buffer::textureFilterOperation
Specifies the texture filtering mode...
\value Buffer.Nearest Use nearest-neighbor filtering.

QDoc은 QML 모듈 식별자를 포함한 완전한 속성 이름도 허용합니다:

\qmlproperty bool QtQuick.Controls::Button::highlighted

지정된 경우, 모듈 식별자(위의 QtQuick.Controls)는 관련 문서에서 \inqmlmodule\qmltype 명령에 전달된 값과 일치해야 합니다. 속성이 속한 QML 유형의 이름이 문서 프로젝트 내의 모든 유형 중에서 고유한 경우, 모듈 식별자는 생략할 수 있습니다.

\qmlsignal

\qmlsignal 명령어는 QML 신호를 문서화하기 위한 것입니다. 인수는 해당 줄의 나머지 부분입니다. 인수는 신호가 선언된 QML 유형, :: 한정자, 그리고 마지막으로 신호 이름으로 구성되어야 합니다. clicked() 라는 이름의 QML 신호가 있다면, 이에 대한 문서는 다음과 같이 작성됩니다:

/*!
    \qmlsignal MouseArea::clicked(MouseEvent mouse)

    This signal is emitted when there is a click. A click is defined as a
    press followed by a release, both inside the MouseArea.
*/

QDoc은 이 문서를 MouseArea 타입의 QML 참조 페이지에 포함시킵니다.

\qmlmodule

\qmlmodule 명령어를 사용하여 QML 모듈 페이지를 생성할 수 있습니다. QML 모듈 페이지는 QML 유형이나 관련 자료의 모음입니다. 이 명령어는 선택 사항인 <VERSION> 번호 인수를 받으며, group 명령어와 유사합니다.

QML 타입은 해당 타입을 설명하는 주석 블록에 \inqmlmodule 명령을 추가하여 모듈과 연관시킵니다. 모듈 이름 앞에 두 개의 콜론(::)을 붙여 QML 모듈의 모든 멤버에 링크할 수 있습니다.

/*!
    A link to the TabWidget of the UI Component is \l {UIComponent::TabWidget}.
*/

QDoc은 해당 모듈의 모든 멤버를 나열하는 모듈 페이지를 생성합니다.

/*!
    \qmlmodule ClickableComponents

    This is a list of the Clickable Components set. A Clickable component
    responds to a \c clicked() event.
*/

\inqmlmodule

QML 타입은 \inqmlmodule 명령어를 \qmltype 이 명령은 버전 번호를 제외한 모듈(import) 이름을 유일한 인수로 받습니다.

QML 모듈 이름은 (\qmlmodule 명령어로 문서화된 QML 모듈과 일치해야 합니다.

/*!
    \qmltype ClickableButton
    \inqmlmodule ClickableComponents

    A clickable button that responds to the \c click() event.
*/

QDoc은 QML 유형 참조 페이지 상단의 표에 import <qmlmodule>이라는 Import 문 한 줄을 출력합니다.

QML 타입에 링크할 때, 링크 대상에 QML 모듈 식별자가 나타날 수 있습니다. 예를 들어:

\l {ClickableComponents::}{ClickableButton}

ClickableButton을 링크 텍스트로 사용하는 타입 참조 페이지로의 링크입니다.

\instantiates

\instantiates 명령어는 Qt 6.8부터 더 이상 권장되지 않습니다. 대신 \nativetype 를 대신 사용하십시오.

\nativetype

\nativetype 명령어는 \qmltype topic 명령어와 함께 사용해야 합니다. 이 명령어는 C++ 클래스를 인수로 받습니다. QDoc이 해당 C++ 클래스를 찾을 수 없는 경우 경고를 표시합니다. 이 명령어는 Qt 6.8에서 도입되었습니다.

\nativetype 명령어를 사용하여 C++에서 해당 타입의 이름을 지정하십시오. 이렇게 하면 QML 타입에 대한 문서에 생성된 필수 사항(requisites) 블록에 “In C++” 항목이 포함되도록 보장됩니다. 해당 C++ 클래스에는 이에 상응하는 “In QML” 항목이 표시됩니다.

하나의 QML 유형에는 하나의 네이티브 유형만 가질 수 있습니다. 재정의가 발생하면 QDoc은 경고를 표시합니다. 그러나 여러 QML 유형이 동일한 C++ 클래스를 네이티브 유형으로 가질 수 있습니다. C++ 클래스 문서에는 QML 내의 모든 해당 유형 목록이 포함됩니다.

/*!
    \qmltype Transform
    \nativetype QGraphicsTransform
    \inqmlmodule QtQuick

    \brief Provides a way to build advanced transformations on Items.

    The Transform element is a base type which cannot be
    instantiated directly.
*/

여기서 \qmltype 주제에는 \nativetype Transform이 C++에서 QGraphicsTransform 로 호출된다는 점을 명시합니다.

\typealias

\typealias 명령어는 \typedef와 유사하지만, C++ 타입 별칭을 문서화하는 데 특화되어 있습니다:

class Foo
{
public:
    using ptr = void*;
// ...
}

이를 다음과 같이 문서화할 수 있습니다.

/*!
    \typealias Foo::ptr
*/

\typealias 명령어는 QDoc 5.15에서 도입되었습니다.

참조: \typedef.

\typedef

\typedef 명령어는 C++ typedef에 대한 설명 문서를 작성하는 데 사용됩니다. 인수는 typedef의 이름입니다. 해당 typedef에 대한 설명 문서는 typedef가 선언된 클래스, 네임스페이스 또는 헤더 파일의 참조 문서에 포함됩니다. \typedef 를 클래스, 네임스페이스 또는 헤더 파일과 연관시키려면, \typedef 주석에 \relates 명령어를 포함해야 합니다.

/*!
    \typedef QObjectList
    \relates QObject

    Synonym for QList<QObject>.
*/

그 외의 typedef는 이를 정의한 클래스의 참조 페이지에 위치합니다.

/*!
    \typedef QList::Iterator

    Qt-style synonym for QList::iterator.
*/

참조 \typealias.

\variable

\variable 명령어는 클래스 멤버 변수나 상수에 대한 문서를 작성하는 데 사용됩니다. 인수는 변수나 상수의 이름입니다. \variable 명령어의 주석에는 \brief 명령을 포함합니다. QDoc은 \brief 명령의 텍스트를 기반으로 문서를 생성합니다.

문서는 관련 클래스, 헤더 파일 또는 네임스페이스 문서 내에 위치하게 됩니다.

멤버 변수의 경우:

/*!
    \variable QStyleOption::palette
    \brief The palette that should be used when painting
           the control
*/

\variable 명령어를 사용하여 상수를 문서화할 수도 있습니다. 예를 들어, QTreeWidgetItem 클래스에 Type 및 UserType 상수가 있다고 가정해 보겠습니다:

enum { Type = 0, UserType = 1000 };

이 경우, ` \variable ` 명령어를 다음과 같이 사용할 수 있습니다:

/*!
    \variable QTreeWidgetItem::Type

    The default type for tree widget items.

    \sa UserType, type()
*/

/*!
    \variable QTreeWidgetItem::UserType

    The minimum value for custom types. Values below
    UserType are reserved by Qt.

    \sa Type, type()
*/