Estilo de documentación C

Para generar la documentación, QDoc recorre el código fuente y genera documentación para tipos C++ como clases. A continuación, QDoc asocia funciones miembro, propiedades y otros tipos a la clase apropiada.

Tenga en cuenta que la documentación debe estar en los archivos de implementación como .cpp.

Documentación de clases

La documentación de clases se genera utilizando el comando \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
*/

Loscomandos de contexto añaden información sobre la clase, como su módulo o la versión en la que se añadió la clase.

Algunos comandos de contexto comunes son:

• \brief - la breve descripción de la clase (obligatoria)
• \since - la versión a la que se añadió la clase (obligatorio)
• \internal - marca la clase como interna. Las clases internas no aparecen en la documentación pública de la API.

La descripción breve y detallada

La descripción breve se marca con el comando \brief y sirve para resumir el propósito o la funcionalidad de la clase. Para clases C++, QDoc tomará la clase y creará información anotada para la clase. La información anotada aparece en listas y tablas que muestran la clase.

El resumen C++ debe comenzar con:

"The <C++ class name> class"

La sección de descripción detallada comienza después de 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 vacía que separe la descripción breve de la detallada.

Funciones miembro

Normalmente, la documentación de las funciones precede inmediatamente a la implementación de la función en el archivo .cpp. Para la documentación de funciones que no esté inmediatamente encima de la implementación, se necesita el símbolo \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 comunes para la documentación de funciones:

• "Construye..." - 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.

/*!
    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 inmediatamente por encima de la implementación de la función de lectura. El comando de tema 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() const

La documentación de propiedades suele comenzar con "Esta propiedad...", pero se trata de expresiones alternativas:

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

La documentación de las propiedades debe incluir

• descripción y comportamiento de la propiedad
• valores aceptados para la propiedad
• el valor por defecto de la propiedad

De forma similar a 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 van de 0.0 (sin desenfoque) a maximumRadius (máximo desenfoque). 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 señales suele comenzar con "Esta señal se activa cuando...". A continuación se presentan estilos alternativos:

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

En el caso de las ranuras 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..."

Para las propiedades que tienen señales sobrecargadas, QDoc agrupa los notificadores sobrecargados. Para referirse a una versión específica de un notificador o señal, basta con referirse a la propiedad y mencionar 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.
*/

Enums, espacios de nombres y otros tipos

Los enums, namespaces y macros tienen un comando topic para su documentación:

• \enum
• \typedef
• \macro

El estilo del lenguaje para estos tipos menciona que son un enum o una macro y continúa con la descripción del tipo.

Para las enumeraciones, el comando \value sirve para listar los valores. QDoc crea una tabla de valores para el enum.

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