항목 간 연관 설정

관계 지정 명령어는 문서화된 요소 하나가 다른 문서화된 요소와 어떤 관계를 맺는지 지정하는 데 사용됩니다. 몇 가지 예시:

• 이 함수는 다른 함수의 오버로드입니다.
• 이 함수는 다른 함수의 재구현입니다.
• 이 typedef는 특정 클래스나 헤더 파일과 관련이 있습니다.

또한 QML 유형이 다른 QML 유형을 상속한다는 사실을 문서화하는 명령어도 있습니다.

명령어

\inherits

\inherits 명령어는 한 QML 유형이 다른 QML 유형을 상속한다는 사실을 문서화하기 위한 것입니다. 이 명령어는 상속하는 요소의 \qmltype 주석에 포함되어야 합니다. 인수는 상속받는 QML 유형의 이름이며, 선택적으로 QML 모듈 이름을 붙여 지정할 수 있습니다.

/*!
    \qmltype PauseAnimation
    \inqmlmodule QtQuick
    \nativetype QDeclarativePauseAnimation
    \ingroup qml-animation-transition
    \since 4.7
    \inherits Animation
    \brief The PauseAnimation element provides a pause for an animation.

    When used in a SequentialAnimation, PauseAnimation is a step
    when nothing happens, for a specified duration.

    A 500ms animation sequence, with a 100ms pause between two animations:

    SequentialAnimation {
        NumberAnimation { ... duration: 200 }
        PauseAnimation { duration: 100 }
        NumberAnimation { ... duration: 200 }
    }

    \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example}
*/

QDoc은 PauseAnimation 요소의 참조 페이지에 다음 줄을 포함합니다:

상속 Animation

.qml 파일에서 QML 타입을 직접 문서화할 때, QDoc은 QML 구문을 통해 기본 타입을 자동으로 감지할 수 있으므로 일반적으로 \inherits 명령은 필요하지 않습니다. \inherits 명령이 지정된 경우, 이 명령이 자동 기본 타입 감지 기능을 무시합니다.

\overload

C++ 함수 오버로드를 표시하려면 \overload 명령을 사용하여 C++ 함수 오버로드를 표시하십시오. 이 명령은 문서 주석 내에서 별도의 줄에 위치해야 합니다.

작동 방식

다른 매개변수를 사용하여 유사한 작업을 수행하는 동일한 이름의 C++ 함수(오버로드)가 여러 개 있는 경우, \overload 를 사용하여 문서화가 중복되는 것을 방지하십시오. \overload 는 완전한 문서가 필요하지 않습니다. \overload 가 있는 함수는 구체적인 차이점에 중점을 둘 수 있습니다.

로 표시된 함수는 \overload 로 표시된 함수는 메인 함수의 문서를 참조하므로, 누락된 매개변수에 대한 경고를 자동으로 무시합니다.

기본 사용법

/*!
    \overload
    Brief description of what makes this overload different.
*/

주 함수에 연결하기

주요 함수로 연결되는 링크를 생성하려면 함수 이름을 추가하세요:

/*!
    \overload functionName()
    Brief description of what makes this overload different.
*/

완전한 이름(ClassName::functionName())이나 간략한 이름(functionName())을 사용하십시오. QDoc은 현재 클래스나 네임스페이스를 사용하여 간략한 이름을 자동으로 완전한 이름으로 변환합니다.

주 오버로드 지정

기본적으로 QDoc은 주 오버로드를 자동으로 선택합니다. 어떤 오버로드를 주 오버로드로 명시적으로 지정하려면 다음을 사용하십시오:

/*!
    \overload primary
    Main documentation for this function family.
    Document all parameters here.
*/

주 오버로드:

• 메인 함수의 문서화를 포함합니다.
• 매개변수에 대한 완전한 설명이 포함되어야 합니다.
• "이 함수는 다음을 오버로드합니다..."라는 문구를 표시하지 마십시오.
• 다른 오버로드의 링크 대상 역할을 합니다.

가장 중요한 오버로드가 QDoc의 자동 선택과 다를 때, 또는 일관된 링크 동작이 필요할 때는 주로 `\overload `를 사용하십시오.

\reimp

\reimp 명령어는 추가 문서화 없이도 해당 함수가 가상 함수의 재구현임을 나타내기 위한 것입니다.

기본적으로 QDoc은 문서화가 되어 있지 않은 경우, 재구현된 가상 함수를 클래스 참조에서 제외합니다. 이 명령을 사용하면 문서화되지 않은 함수도 반드시 포함되도록 보장할 수 있습니다.

이 명령어는 별도의 줄에 단독으로 작성해야 합니다.

/*!
    \reimp
*/
void QToolButton::nextCheckState()
{
    Q_D(QToolButton);
    if (!d->defaultAction)
        QAbstractButton::nextCheckState();
    else
        d->defaultAction->trigger();
}

이 함수는 문서에 포함되지 않습니다. 대신, 문서에 기본 함수 QAbstractButton::nextCheckState()에 대한 링크가 표시됩니다.

\relates

\relates 명령어는 엔티티(함수, 매크로, typedef, enum 또는 변수)의 문서를 클래스, 네임스페이스 또는 헤더 파일에 포함시키기 위한 것입니다. 인수는 해당 엔티티와 관련된 클래스, 네임스페이스 또는 헤더의 이름입니다.

인수가 템플릿 유형을 가리키는 경우, 템플릿 매개변수 없이 유형 이름만 사용하십시오.

/*!
    \relates QChar

    Reads a char from the stream \a in into char \a chr.

    \sa {Format of the QDataStream operators}
*/
QDataStream &operator>>(QDataStream &in, QChar &chr)
{
    quint16 u;
    in >> u;
    chr.unicode() = ushort(u);
    return in;
}

이 함수에 대한 설명은 ` QChar` 클래스의 참조 페이지에 있는 '관련 비멤버(Related Non-members )' 섹션에 포함되어 있습니다.