Estilo de documentación de QML
QDoc puede procesar tipos QML definidos como clases de C++ y tipos QML definidos en archivos « .qml ». Para las clases de 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 de C++ también deben documentarse con los comandos de tema de QML:
- \qmlattachedmethod
- \qmlattachedproperty
- \qmlattachedsignal
- \qmlvaluetype
- \qmltype
- \qmlmethod
- \qmlproperty
- \qmlsignal
- \qmlmodule
- \inqmlmodule
- \nativetype
En el caso de los tipos QML definidos en archivos .qml, QDoc analizará el código QML y determinará las propiedades, las señales y el tipo dentro de la definición QML. El bloque QDoc debe situarse inmediatamente encima de la declaración. En el caso de los tipos QML implementados en C++, QDoc generará advertencias si no existe la documentación de la clase C++. La documentación de la clase puede marcarse como «internal» si no se trata de una API pública.
Tipos QML
El \qmltype comando sirve 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 \nativetype comando acepta como argumento la clase de C++ que implementa el tipo QML. Para los tipos implementados en QML, esto no es necesario.
La descripción breve ofrece un resumen del tipo QML. No es necesario que la descripción breve 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 valuesA continuación se ofrecen 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 de código y enlaces a otra documentación.
Propiedades
La descripción de la propiedad se centra en lo que hace la propiedad y puede seguir el siguiente estilo:
La documentación de las propiedades suele comenzar con «Esta propiedad...», pero para ciertas propiedades, estas son las expresiones más habituales:
- «Esta propiedad contiene...»
- «Esta propiedad describe...»
- «Esta propiedad representa...»
- «Devuelve
truecuando... yfalsecuando...» —para propiedades marcadas comoread-only. - «Establece el...» —para propiedades que configuran un tipo.
Documentación sobre señales y controladores
Las señales de QML se documentan bien en el archivo QML, bien en la implementación en C++ mediante el \qmlsignal comando. La documentación de una señal debe incluir la condición para emitirla, mencionar el controlador de señal correspondiente y especificar si la señal admite algún 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 activa cuando...»
- «Se activa cuando...»
- «Se emite cuando...»
Métodos y funciones QML
Normalmente, la documentación de una función precede inmediatamente a la implementación de la misma en el archivo .cpp. El comando «topic» para las funciones es \fn. En el caso de las funciones en QML, la documentación debe aparecer justo 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 habituales en la documentación de funciones:
- «Copia...» —para constructores
- «Destruye...»: para destructores
- «Devuelve...»: para funciones de acceso
La documentación de la función debe especificar:
- el tipo de retorno
- los parámetros
- las acciones de las funciones
El \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 \c en el caso de los valores booleanos.
Enumeraciones
Las enumeraciones de QML se documentan como propiedades de QML con el \qmlenum comando. Utiliza el \value comando para documentar los valores de la enumeración. Añade 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.BlackEl comentario de QDoc enumera los valores de la enumeración.
Si la enumeración está implementada en C++, plantéate utilizar el \qmlenumeratorsfrom comando. Si esto no es posible, la documentación también puede enlazar directamente a la enumeración de C++ correspondiente. Sin embargo, el comentario de QDoc debería indicar entonces que la enumeración es una enumeración de C++.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.