상태

이 명령어들은 문서화된 요소가 특별한 상태를 가지고 있음을 나타내기 위한 것입니다. 해당 요소는 더 이상 사용되지 않을 예정이며, 공개 인터페이스에 더 이상 포함되지 않게 될 수 있으므로 '사용 중단( deprecated)'으로 표시될 수 있습니다. \since 명령어는 함수나 클래스가 처음 등장한 버전 번호를 지정하는 데 사용됩니다. \qmlabstract 명령어는 QML 유형을 추상 기본 클래스로 표시하는 데 사용됩니다.

\abstract 그리고 \qmlabstract

\abstract는 ` \qmlabstract ` 명령어의 동의어입니다. 해당 QML 유형이 추상 기본 유형으로만 사용되도록 의도된 경우, 이 명령어를 \qmltype 해당 유형이 추상 기본 유형으로만 사용되도록 의도된 경우, QML 유형의 주석에 이 명령어를 추가하십시오. QML 유형이 추상일 경우, 해당 QML 유형은 인스턴스화될 수 없음을 의미합니다. 대신, 해당 유형의 공개 API에 포함된 속성들은 해당 추상 QML 유형을 상속하는 각 QML 유형의 참조 페이지에 있는 공개 속성 목록에 포함됩니다. 이러한 속성들은 마치 상속하는 QML 유형의 속성인 것처럼 문서화됩니다.

일반적으로 QML 유형이 \qmlabstract로 표시되면, 참조 페이지가 생성되지 않도록 \internal 로 표시되어 참조 페이지가 생성되지 않습니다. 추상 QML 유형이 internal로 표시되지 않은 경우, 문서에 참조 페이지가 생성됩니다.

\attribution

\attribution 명령어는 문서화된 \page 를 라이선스 출처 문서로 표시합니다.

\generatelist annotatedattributions 명령어는 문서 프로젝트 내의 모든 라이선스 출처 표기 페이지에 대한 주석이 달린 목록을 생성합니다.

\default

\default 명령어는 QML 속성의 기본값을 문서화하는 데 사용됩니다. 이 명령어는 단일 인수를 받으며, 이 인수는 문서에서 기본값으로 표시됩니다.

/*!
    \qmlproperty real Item::x
    \default 0.0
*/

기본값이 비어 있지 않은 문자열인 경우 따옴표를 사용하십시오:

/*!
    \qmlproperty string Item::state
    \default "invalid"
*/

\compares

\compares 명령어를 사용하여, 문서화된 C++ 유형을 그 자체와 비교했을 때의 비교 결과를 설명하십시오. 이 명령어는 반드시 \class 명령과 함께 사용해야 합니다.

\compares 다음 인자 중 하나를 받습니다:

• strong
• partial
• weak
• equality

strong, partial, weak 는 비교 순서와 관련이 있습니다. equality 는 해당 유형에 대해서만 동일성 비교만 수행함을 의미합니다.

이 명령어는 Qt 6.7부터 QDoc에 도입되었습니다.

참조 \compareswith.

\compareswith

\compareswith .. \endcompareswith 명령어 쌍을 사용하여, 문서화된 C++ 유형을 다른 유형과 비교했을 때의 비교 결과를 설명하십시오. ` \compareswith `는 두 개 이상의 인자를 받습니다. 비교 범주 뒤에 유형 이름 하나 또는 공백으로 구분된 유형 이름 목록이 이어집니다. ` \compareswith ` 및 ` \endcompareswith ` 명령어 사이에 있는 모든 텍스트 줄은 비교 범주 인자에 해당하는 모든 유형에 적용되는 추가 세부 정보로 간주됩니다.

unsigned long 와 같이 이름에 공백이 하나 이상 포함된 유형은 중괄호로 묶어야 합니다.

예를 들어:

/*!
    ...
    \compareswith strong int long {unsigned long} {unsigned int} char
    ...
    \endcompareswith
    ...
*/

중괄호로 묶인 인수의 앞뒤 공백은 제거됩니다. 예를 들어, unsigned long 과 unsigned long 은 동일합니다.

비교 범주 인수는 다음 중 하나여야 합니다:

• strong
• partial
• weak
• equality

strong, partial, weak 는 정렬 순서와 관련이 있습니다. equality 는 해당 유형이 동일성 비교만 수행됨을 의미합니다.

이 명령어는 Qt 6.7부터 QDoc에 도입되었습니다.

참조 \compares.

\qmldefault

\qmldefault 명령어는 QML 속성을 기본 속성으로 지정하는 데 사용됩니다. 속성 설명에는 ‘ default ’라는 문구가 표시됩니다.

/*!
    \qmlproperty list<Change> State::changes
    This property holds the changes to apply for this state.
    \qmldefault

    By default, these changes are applied against the default state. If the state
    extends another state, then the changes are applied against the state being
    extended.
*/

State 유형의 참조 페이지에서 QDoc이 이 속성을 어떻게 렌더링하는지 확인해 보세요.

\qmlenumeratorsfrom

\qmlenumeratorsfrom 명령어를 \qmlproperty 속성 유형 열거형이 포함된 항목에서 `xml-ph-0000@deepl.internal` 명령어를 사용하여 C++ \enum 주제에서 열거자에 대한 문서를 자동으로 복제할 수 있습니다.

이 명령어는 완전히 정규화된 C++ 열거형을 인수로 받아, 열거자 목록과 해당 설명을 생성합니다.

기본적으로 각 열거형 이름 앞에는 해당 속성이 속한 유형 이름이 접두사로 붙으며, 구분자로 ‘ . ’가 사용됩니다.

예를 들어:

/*!
    \qmlproperty enumeration QtMultimedia::Camera::error
    \qmlenumeratorsfrom QCamera::Error

    //! Outputs documentation for 'Camera.NoError', 'Camera.CameraError'
*/

열거자가 QML에 다른 타입 이름으로 등록된 경우, 이 이름(접두사)을 대괄호 안의 선택적 인수를 사용하여 지정할 수 있습니다:

    \qmlenumeratorsfrom [Errors] QCamera::Error

    //! Outputs documentation for 'Errors.NoError', 'Errors.CameraError'
\1/

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

참조 \qmlproperty, \enum, 그리고 \value.

\dontdocument

\dontdocument 명령어는 특정 모듈의 dontdocument.qdoc 파일에서만 사용됩니다. 이 파일은 문서화 대상이 아닌 공개적으로 선언된 클래스나 구조체를 지정합니다. QDoc은 이러한 클래스와 구조체에 대해 \class 주석이 누락되었다는 경고 메시지를 표시하지 않습니다.

아래는 위젯(widgets)용 dontdocument.qdoc 파일에 포함된 \dontdocument 명령어입니다:

/*!
   \dontdocument (QTypeInfo QMetaTypeId)
*/

\inheaderfile

\inheaderfile 메타명령어는 C++ 클래스, 네임스페이스 또는 헤더 파일 참조 문서를 위해 생성된 include 문장을 재정의하는 데 사용됩니다.

기본적으로 QDoc은 ` \class SomeClass `을 다음과 같은 include 문으로 사용할 수 있도록 문서화합니다:

#include <SomeClass>

실제 include 문이 기본값과 다른 경우, 다음과 같이 문서화할 수 있습니다.

\class SomeClass
\inheaderfile Tools/SomeClass
...

참조 \class 및 \headerfile.

\obsolete

\obsolete 명령어는 \deprecated 명령어로 대체되었습니다.

이 명령어는 하위 호환성을 위해 유지되고 있을 뿐입니다. 향후 QDoc 버전에서 제거될 수 있습니다. 대신 \deprecated 명령어를 사용하십시오.

참조 \deprecated.

\deprecated

\deprecated 명령어는 해당 요소가 더 이상 사용되지 않는 것으로 지정하고, 새로운 코드에서는 더 이상 사용해서는 안 됨을 나타내기 위한 것입니다.

\deprecated 명령어에는 두 개의 선택적 인수가 있습니다:

• 대괄호([])로 묶인 버전(예: [6.2]).
• 추가 정보(예: 권장 대체 항목)가 포함된 문자열.

클래스에 대한 참조 문서를 생성할 때, QDoc은 사용 중단된 멤버를 설명하는 별도의 페이지를 생성하고 해당 페이지로 링크를 연결합니다. 이에 상응하는 대체 항목을 제안하는 것이 권장되는 관행입니다.

/*!
    \fn MyClass::MyDeprecatedFunction
    \deprecated [6.2] Use MyNewFunction() instead.
*/

\internal

\internal 명령어는 문서화된 요소가 공개 인터페이스의 일부가 아님을 나타냅니다.

이 명령어는 반드시 별도의 줄에 작성해야 합니다.

QDoc은 관련 클래스 참조 문서를 생성할 때, 문서화된 항목뿐만 아니라 해당 문서도 무시합니다.

/*!
    \internal

    Tries to find the decimal separator. If it can't find
    it and the thousand delimiter is != '.' it will try to
    find a '.';
*/
int QDoubleSpinBoxPrivate::findDelimiter
        (const QString &str, int index) const
{
    int dotindex = str.indexOf(delimiter, index);
    if (dotindex == -1 && thousand != dot && delimiter != dot)
        dotindex = str.indexOf(dot, index);
    return dotindex;
}

-showinternal 명령줄 옵션을 사용하여 QDoc을 호출하거나 QDOC_SHOW_INTERNAL 환경 변수가 설정되어 있지 않은 한, 이 함수는 문서에 포함되지 않습니다.

\modulestate

\module 또는 \qmlmodule 항목 내에서 ` \modulestate ` 명령을 사용하여 사용자 정의 모듈 상태 설명을 제공하십시오.

이 명령어는 모듈의 상태를 설명하는 인수를 받습니다. 예를 들어:

/*!
    \module QtFoo
    \modulestate Experimental
*/

그러면 QDoc은 이 정보를 모듈 페이지에 추가합니다:

이 모듈은 '실험적 ' 상태입니다.

HTML 출력에서 이 상태 정보는 모듈 구성원들의 참조 페이지 내 탐색 모음(브레드크럼)에도 표시됩니다.

참조: \preliminary.

\preliminary

\preliminary 명령어는 문서화된 요소가 아직 개발 중임을 나타내기 위한 것입니다.

이 명령어는 반드시 별도의 줄에 위치해야 합니다.

\preliminary 명령어는 문서 내에서 주석으로 확장되며, 목록에 해당 요소가 나타날 때 이를 ‘예비’ 상태로 표시합니다.

/*!
    \preliminary

    Returns information about the joining type attributes of the
    character (needed for certain languages such as Arabic or
    Syriac).

*/
QChar::JoiningType QChar::joiningType() const
{
    return QChar::joiningType(ucs);
}

QDoc 버전 6.12부터는 \preliminary 로 표시된 요소에 대해 상태 설명자와 생성된 주석의 내용을 사용자 정의할 수 있습니다.

참조: preliminary 구성 변수.

\readonly

\readonly 명령어는 \qmlproperty 명령과 함께 사용되어 QML 속성을 읽기 전용으로 지정합니다.

\required

\required 명령어는 \qmlproperty 명령과 함께 사용되어 QML 속성을 필수로 지정합니다.

‘속성 시스템’ 항목도 참조하십시오.

\since

\since 명령어는 해당 기능이 추가된 마이너 릴리스 버전을 알려줍니다.

\since 에 전달된 인자에 공백이 포함되어 있지 않으면, 이는 productname의 약어 표기법으로 간주되며, QDoc은 생성된 출력에서 버전 앞에 productname 의 값을 접두사로 추가합니다. productname 변수가 정의되어 있지 않으면, QDoc은 버전 문자열만 생성합니다.

인수에 제품명을 명시적으로 포함할 수도 있습니다:

\since MyFramework 2.0

이 경우, 인자(제품명 및 버전)는 있는 그대로 사용됩니다.

'Since' 정보의 상속

QDoc 버전 6.5부터, C++ 클래스와 QML 타입은 타입 문서에서 ` \since `가 명시적으로 사용되지 않는 한, 각 모듈 또는 QML 모듈의` \since ` 문을 상속받습니다.

Since 절

\value 명령어는 명령어 문자열 바로 뒤에 대괄호로 묶인 선택적 since 절을 추가할 수 있습니다. 이는 특정 C++ 열거형 값에 since 정보를 지정하는 데 사용됩니다.

참조 \value 및 ignoresince.

\wrapper

\wrapper 명령어는 C++ 클래스 문서에서 사용될 때, 해당 클래스를 Qt가 아닌 API에 대한 접근을 제공하는 래퍼로 표시합니다. 이 명령어는 해당 클래스의 멤버에 대해 발생했을 수 있는 경고를 억제하는 데 사용됩니다.