Estilo de documentación de C++
Para generar la documentación, QDoc recorre el código fuente y genera documentación para tipos de C++, como las clases. A continuación, QDoc asocia las funciones miembro, las propiedades y otros tipos a la clase correspondiente.
Ten en cuenta que la documentación debe encontrarse en los archivos de implementación, como .cpp.
Documentación de clases
La documentación de clases se genera utilizando el \class y el nombre de la clase como primer argumento.
/*!
\class QCache
\brief The QCache class is a template class that provides a cache.
\ingroup tools
\ingroup shared
\reentrant
QCache\<Key, T\> defines a cache that stores objects of type T
associated with keys of type Key. For example, here's the
definition of a cache that stores objects of type Employee
associated with an integer key:
\snippet code/doc_src_qcache.cpp 0
Here's how to insert an object in the cache:
\snippet code/doc_src_qcache.cpp 1
... detailed description omitted
\sa QPixmapCache, QHash, QMap
*/Los comandos de contexto añaden información sobre la clase, como su módulo o en qué versión se añadió la clase.
Algunos comandos de contexto habituales son:
- \brief - la breve descripción de la clase (obligatoria)
- \since - la versión en la que se añadió la clase (obligatorio)
- \internal - marca la clase como interna. Las clases internas no aparecen en la documentación de la API pública.
La descripción breve y la descripción detallada
La descripción breve se indica con el \brief y sirve para resumir la finalidad o la funcionalidad de la clase. En el caso de las clases de C++, QDoc tomará la clase y creará información anotada para la misma. La información anotada aparece en listas y tablas que muestran la clase.
La descripción breve en C++ debe comenzar con:
"The <C++ class name> class"La sección de descripción detallada comienza tras la descripción breve. Proporciona más información sobre la clase. La descripción detallada puede contener imágenes, fragmentos de código o enlaces a otros documentos relevantes. Debe haber una línea en blanco que separe la descripción breve de la detallada.
Funciones miembro
Normalmente, la documentación de una función precede inmediatamente a la implementación de la misma en el archivo « .cpp ». Para la documentación de una función que no se encuentre inmediatamente encima de la implementación, se necesita la etiqueta \fn es necesario.
/*!
\fn QString &QString::remove(int position, int n)
Removes \a n characters from the string, starting at the given \a
position index, and returns a reference to the string.
If the specified \a position index is within the string, but \a
position + \a n is beyond the end of the string, the string is
truncated at the specified \a position.
\snippet qstring/main.cpp 37
\sa insert(), replace()
*/
QString &QString::remove(int pos, int len)La documentación de la función comienza con un verbo que indica la operación que realiza la función. Esto también se aplica a los constructores y destructores.
Algunos verbos habituales para la documentación de funciones:
- «Construye...» —para constructores
- «Destruye...» —para destructores
- «Devuelve...» —para funciones de acceso—
La documentación de la función debe indicar:
- 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.
/*!
Returns \c true if a QScroller object was already created for \a target; \c false otherwise.
\sa scroller()
*/
bool QScroller::hasScroller(QObject *target)Propiedades
La documentación de las propiedades se encuentra justo encima de la implementación de la función de lectura. El comando «topic» para las propiedades es \property.
/*!
\property QVariantAnimation::duration
\brief the duration of the animation
This property describes the duration in milliseconds of the
animation. The default duration is 250 milliseconds.
\sa QAbstractAnimation::duration()
*/
int QVariantAnimation::duration() constLa documentación de las propiedades suele comenzar con «Esta propiedad...», pero existen otras expresiones alternativas:
- «Esta propiedad contiene...»
- «Esta propiedad describe...»
- «Esta propiedad representa...»
- «Devuelve
truecuando... yfalsecuando...» —para propiedades de lectura—. - «Establece el...» —para propiedades que configuran un tipo.
La documentación de la propiedad debe incluir:
- la descripción y el comportamiento de la propiedad
- los valores aceptados para la propiedad
- el valor por defecto de la propiedad
Al igual que con las funciones, el tipo por defecto puede vincularse o marcarse con el comando « \c ».
Un ejemplo de estilo de rango de valores es:
Los valores oscilan entre 0,0 (sin desenfoque) y maximumRadius (desenfoque máximo). Por defecto, la propiedad se establece en 0,0 (sin desenfoque).
Señales, notificadores y ranuras
El comando de tema para señales, notificadores y ranuras es \fn. La documentación de las señales indica cuándo se activan o emiten.
/*!
\fn QAbstractTransition::triggered()
This signal is emitted when the transition has been triggered (after
onTransition() has been called).
*/La documentación de las señales suele comenzar con «Esta señal se activa cuando...». A continuación se muestran otros estilos:
- «Esta señal se activa cuando...»
- «Se activa cuando...»
- «Se emite cuando...»
En el caso de los slots o los notificadores, debe documentarse la condición en la que se ejecutan o son activados por una señal.
- «Se ejecuta cuando...»
- «Esta ranura se ejecuta cuando...»
En el caso de las propiedades que tienen señales sobrecargadas, QDoc agrupa los notificadores sobrecargados. Para hacer referencia a una versión específica de un notificador o una señal, basta con mencionar la propiedad e indicar que existen diferentes versiones del notificador.
/*!
\property QSpinBox::value
\brief the value of the spin box
setValue() will emit valueChanged() if the new value is different
from the old one. The \l{QSpinBox::}{value} property has a second notifier
signal which includes the spin box's prefix and suffix.
*/Enumeraciones, espacios de nombres y otros tipos
Las enumeraciones, los espacios de nombres y las macros tienen un comando de tema para su documentación:
El estilo de lenguaje para estos tipos indica que se trata de una enumeración o una macro y continúa con la descripción del tipo.
En el caso de las enumeraciones, el \value comando sirve para enumerar los valores. QDoc crea una tabla de valores para la enumeración.
/*!
\enum QSql::TableType
This enum type describes types of SQL tables.
\value Tables All the tables visible to the user.
\value SystemTables Internal tables used by the database.
\value Views All the views visible to the user.
\value AllTables All of the above.
*/© 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.