QML 문서 작성 스타일

QDoc은 C++ 클래스로 정의된 QML 유형과 .qml 파일에 정의된 QML 유형을 처리할 수 있습니다. QML 유형으로 문서화된 C++ 클래스의 경우, QDoc 주석은 .cpp 파일에 포함되며, QML로 정의된 QML 유형의 주석은 .qml 파일에 포함됩니다. 또한 C++ 클래스는 다음 QML 토픽 명령어를 사용하여 문서화되어야 합니다:

• \qmlattachedmethod
• \qmlattachedproperty
• \qmlattachedsignal
• \qmlvaluetype
• \qmltype
• \qmlmethod
• \qmlproperty
• \qmlsignal
• \qmlmodule
• \inqmlmodule
• \nativetype

.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` \nativetype 명령은 QML 타입을 구현하는 C++ 클래스를 인수로 받습니다. QML로 구현된 타입의 경우, 이는 필요하지 않습니다.

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

\qmltype ColorAnimation
\brief Animates changes in color values

다음은 간략한 설명에 사용할 수 있는 몇 가지 동사 예시입니다:

• "~을(를) 제공합니다..."
• "~을 지정합니다..."
• "설명합니다..."

상세 설명은 간략한 설명 다음에 이어지며, 이미지, 코드 예제 및 다른 문서로 연결되는 링크를 포함할 수 있습니다.

속성

속성 설명은 해당 속성이 수행하는 기능에 중점을 두며, 다음과 같은 형식을 사용할 수 있습니다:

속성 문서는 대개 "이 속성은..."으로 시작하지만, 특정 속성의 경우 다음과 같은 표현이 흔히 사용됩니다:

• "이 속성은..."
• "이 속성은 ...을 설명합니다."
• "이 속성은 ...을 나타냅니다."
• "다음과 같은 경우 ` true `를 반환하고, 다음과 같은 경우 ` false `를 반환합니다." — ` read-only`로 표시된 속성의 경우.
• "…를 설정합니다." - 타입을 구성하는 속성의 경우.

신호 및 핸들러 문서

QML 시그널은 QML 파일 내 또는 C++ 구현에서 \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 파일에서 함수 구현부 바로 앞에 위치합니다. 함수에 대한 topic 명령어는 \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 열거형은 \qmlenum 명령어를 사용하여 QML 속성으로 문서화됩니다. 열거형 값을 문서화하려면 \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++ 열거형임을 명시해야 합니다.