Estilo de documentación QML

QDoc puede procesar tipos QML definidos como clases C++ y tipos QML definidos en archivos .qml. En el caso de las clases C++ documentadas como tipos QML, los comentarios de QDoc se encuentran en el archivo .cpp, mientras que los tipos QML definidos en QML se encuentran en el archivo .qml. Las clases C++ también deben documentarse con los comandos de temas QML:

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

Para los tipos QML definidos en archivos .qml, QDoc analizará el QML y determinará las propiedades, señales y el tipo dentro de la definición QML. En ese caso, el bloque QDoc debe situarse inmediatamente encima de la declaración. Para los tipos QML implementados en C++, QDoc emitirá advertencias si no existe la documentación de la clase C++. La documentación de la clase puede marcarse como interna si no se trata de una API pública.

Tipos QML

El comando \qmltype es para la documentación de tipos 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}

El comando \nativetype acepta como argumento la clase C++ que implementa el tipo QML. Para tipos implementados en QML, esto no es necesario.

La breve descripción proporciona un resumen del tipo QML. No es necesario que sea una frase completa y puede comenzar con un verbo. QDoc añadirá la descripción breve al tipo QML en tablas y listas generadas.

\qmltype ColorAnimation
\brief Animates changes in color values

A continuación se indican algunos verbos alternativos para la breve descripción:

• "Proporciona..."
• "Especifica..."
• "Describe..."

La descripción detallada sigue a la breve y puede contener imágenes, fragmentos y enlaces a otra documentación.

Propiedades

La descripción de la propiedad se centra en lo que hace la propiedad y puede utilizar el siguiente estilo:

La documentación de una propiedad suele comenzar con "Esta propiedad...", pero para determinadas propiedades, estas son las expresiones habituales:

• "Esta propiedad sostiene..."
• "Esta propiedad describe..."
• "Esta propiedad representa..."
• "Devuelve true cuando... y false cuando..." - para las propiedades marcadas read-only.
• "Establece el..." - para las propiedades que configuran un tipo.

Documentación de señales y manejadores

Las señales QML se documentan en el archivo QML o en la implementación C++ con el comando \qmlsignal . La documentación de las señales debe incluir la condición para emitir la señal, mencionar el manejador de señal correspondiente y documentar si la señal acepta un parámetro.

/*
    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()

Estos son los posibles estilos de documentación para las señales

• "Esta señal se dispara cuando..."
• "Se dispara cuando..."
• "Se emite cuando..."

Métodos y funciones QML

Normalmente, la documentación de las funciones precede inmediatamente a la implementación de la función en el archivo .cpp. El comando de tema para las funciones es \fn. Para las funciones en QML, la documentación debe residir inmediatamente encima de la declaración de la función.

La documentación de la función comienza con un verbo, que indica la operación que realiza la función.

/*
    \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)

Algunos verbos comunes para la documentación de funciones:

• "Copia..." - para constructores
• "Destruye..." - para destructores
• "Devuelve..." - para funciones accesorias

La documentación de la función debe documentar

• el tipo de retorno
• los parámetros
• las acciones de las funciones

El comando \a marca el parámetro en la documentación. La documentación del tipo de retorno debe enlazar con la documentación del tipo o estar marcada con el comando \c en el caso de valores booleanos.

Enumeraciones

Las enumeraciones QML se documentan como propiedades QML con el comando \qmlenum comando. Utilice el comando \value para documentar los valores de las enumeraciones. Añada el nombre del tipo como prefijo a cada valor, separado por un punto (.), ya que QDoc no lo hace automáticamente.

/*!
\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

El comentario de QDoc enumera los valores de la enumeración.

Si la enumeración está implementada en C++, considere el uso del comando \qmlenumeratorsfrom . Si esto no es posible, la documentación también puede enlazar directamente con la enumeración C++ correspondiente. Sin embargo, el comentario de QDoc debe advertir que la enumeración es una enumeración C++.