QML 문서 스타일

QDoc은 C++ 클래스로 정의된 QML 유형과 .qml 파일에 정의된 QML 유형을 처리할 수 있습니다. QML 유형으로 문서화된 C++ 클래스의 경우 QDoc 주석은 .cpp 파일에 있고, QML에 정의된 QML 유형은 .qml 파일에 있습니다. 또한 C++ 클래스는 QML 주제 명령을 사용하여 문서화해야 합니다:

• \qmlattachedproperty
• \qmlattachedsignal
• \qmlvaluetype
• \qmltype
• \qmlmethod
• \qmlproperty
• \qmlsignal
• \qmlmodule
• \inqmlmodule
• \네이티브 유형

.qml 파일에 정의된 QML 유형의 경우 QDoc은 QML을 구문 분석하고 QML 정의 내에서 속성, 신호 및 유형을 결정합니다. 그런 다음 QDoc 블록은 선언 바로 위에 있어야 합니다. C++로 구현된 QML 유형의 경우, C++ 클래스 문서가 존재하지 않는 경우 QDoc은 경고를 출력합니다. 클래스 문서가 공개 API가 아닌 경우 내부 문서로 표시될 수 있습니다.

QML 유형

qmltype 명령은 QML 유형 문서를 위한 명령입니다.

    \qmltype TextEdit
    \nativetype QQuickTextEdit
    \inqmlmodule QtQuick
    \ingroup qtquick-visual
    \ingroup qtquick-input
    \inherits Item
    \brief Displays multiple lines of editable formatted text

    The TextEdit item displays a block of editable, formatted text.

    It can display both plain and rich text. For example:

    \qml
        TextEdit {
            width: 240
            text: "<b>Hello</b> <i>World!</i>"
            font.family: "Helvetica"
            font.pointSize: 20
            color: "blue"
            focus: true
        }
    \endqml

    \image declarative-textedit.gif

    ... omitted detailed description

    \sa Text, TextInput, {examples/quick/text/textselection}{Text Selection example}

네이티브 타입 명령은 QML 타입을 구현하는 C++ 클래스를 인수로 받아들입니다. QML로 구현된 타입의 경우 이 옵션이 필요하지 않습니다.

간략한 설명은 QML 유형에 대한 요약을 제공합니다. 요약은 완전한 문장일 필요는 없으며 동사로 시작할 수도 있습니다. QDoc은 테이블 및 생성된 목록의 QML 유형에 간단한 설명을 추가합니다.

\qmltype ColorAnimation
\brief Animates changes in color values

다음은 요약 설명의 대체 동사 몇 가지입니다:

• "제공..."
• "지정..."
• "설명..."

자세한 설명은 요약 다음에 나오며 이미지, 스니펫 및 다른 문서로 연결되는 링크를 포함할 수 있습니다.

속성

속성 설명은 속성의 기능에 중점을 두며 다음과 같은 스타일을 사용할 수 있습니다:

속성 문서는 일반적으로 "이 속성은..."으로 시작하지만 특정 속성의 경우 이러한 표현이 일반적입니다:

• "이 프로퍼티는..."
• "이 프로퍼티는..."
• "이 프로퍼티는..."
• "이 속성은...일 때 true 를 반환하고...일 때 false 를 반환합니다." - read-only 로 표시된 속성의 경우
• "설정..." - 유형을 구성하는 프로퍼티의 경우.

시그널 및 핸들러 문서

QML 신호는 QML 파일에 문서화하거나 \qmlsignal 명령을 사용하여 C++ 구현에 문서화합니다. 신호 문서에는 신호를 내보내기 위한 조건이 포함되어야 하며, 해당 신호 처리기를 언급하고, 신호가 매개변수를 허용하는지 여부를 문서화해야 합니다.

/*
    This signal is emitted when the user clicks the button. A click is defined
    as a press followed by a release. The corresponding handler is
    \c onClicked.
*/
signal clicked()

다음은 신호에 대해 가능한 문서 스타일입니다:

• "이 신호는 다음과 같은 경우에 트리거됩니다..."
• "언제 트리거됨..."
• "언제 방출됨..."

메서드 및 QML 함수

일반적으로 함수 문서는 .cpp 파일에서 함수를 구현하기 바로 앞에 위치합니다. 함수에 대한 주제 명령은 \fn입니다. QML의 함수의 경우 문서는 함수 선언 바로 위에 있어야 합니다.

함수 문서는 함수가 수행하는 작업을 나타내는 동사로 시작합니다.

/*
    \qmlmethod QtQuick2::ListModel::remove(int index, int count = 1)

    Deletes the content at \a index from the model.

    \sa clear()
*/
void QQuickListModel::remove(QQmlV8Function *args)

함수 문서에 자주 사용되는 동사는 다음과 같습니다:

• "복사..." - 생성자의 경우
• "파괴..." - 소멸자의 경우
• "반환..." - 접근자 함수의 경우

함수 문서에는 반드시

• 반환 유형
• 매개변수
• 함수의 동작

a 명령은 문서에서 매개변수를 표시합니다. 반환 유형 문서는 유형 문서에 링크하거나 부울 값의 경우 \c 명령으로 표시해야 합니다.

열거형

QML 열거형은 \qmlproperty 명령을 사용하여 QML 프로퍼티로 문서화됩니다. 속성 유형은 enumeration 입니다. 열거형 값을 문서화하려면 \value 명령을 사용합니다. QDoc은 자동으로 이 작업을 수행하지 않으므로 각 값에 마침표(.)로 구분하여 접두사로 유형 이름을 추가합니다.

/*!
\qmlproperty enumeration QtQuick2::Text::font.weight

Sets the font's weight.

The weight can be one of:
\value Font.Light
\value Font.Normal      The default
\value Font.DemiBold
\value Font.Bold
\value Font.Black

QDoc 주석에는 열거형 값이 나열됩니다.

열거형이 C++로 구현된 경우 \qmlenumeratorsfrom 명령을 사용하는 것이 좋습니다. 이것이 가능하지 않은 경우 문서에서 해당 C++ 열거형에 직접 링크할 수도 있습니다. 그러나 QDoc 주석에 해당 열거형이 C++ 열거형임을 알려야 합니다.