¿Cómo incluyo varios párrafos en la sección "observaciones" usando Doxygen?

Question

que finalmente voy a rendir el impuesto soporte en ángulo que me impuso formato de documentación XML de Microsoft (y lo que es el punto, ya que el entorno MSVC todavía no hace nada de fantasía con ella para C++ proyectos) y cambiar mi proyecto actual para usar Doxygen con una sintaxis de estilo Javadoc.

Es fantástico. La documentación en línea es mucho más fácil de leer y escribir, y la salida generada es mucho más útil y versátil. En particular, tengo la opción MULTILINE_CPP_IS_BRIEF activada, lo que me permite escribir la descripción "breve" que desee y luego dividir mi documentación de "detalles" en párrafos usando líneas en blanco. En otras palabras:

/// Changes the active viewing area of the currently selected region. 
/// 
/// The modification is merely enqueued. This function has no effect until the 
/// FlushRegion() function is called. 
/// 
/// Newly-exposed regions will not be repainted automatically. The user must also 
/// call the UpdateRegion() function on these regions to cause their contents to 
/// be redrawn. 
/// 
/// @param dx The amount, in pixels, to shift the visible region horizontally. 
/// @param dy The amount, in pixels, to shift the visible region vertically. 
/// 
/// @remarks 
/// Note that this function is reentrant, but not thread-safe! 
void ScrollRegion(int dx, int dy); 

Esto me da exactamente la salida de deseo, mientras se mantiene el número de meta-comandos ruidosos como @brief y \details que tengo que usar.

El problema surge cuando trato de incluir un segundo párrafo en mi sección "observaciones", tal como lo hice (implícitamente) en la sección "detalles". Por ejemplo:

/// Changes the active viewing area of the currently selected region. 
/// 
/// The modification is merely enqueued. This function has no effect until the 
/// FlushRegion() function is called. 
/// 
/// Newly-exposed regions will not be repainted automatically. The user must also 
/// call the UpdateRegion() function on these regions to cause their contents to 
/// be redrawn. 
/// 
/// @param dx The amount, in pixels, to shift the visible region horizontally. 
/// @param dy The amount, in pixels, to shift the visible region vertically. 
/// 
/// @remarks 
///  Note that this function is reentrant, but not thread-safe! 
/// 
///  If thread safety is required, the user must handle locking and unlocking 
///  the region manually. 
void ScrollRegion(int dx, int dy); 

La salida generada no interpreta el segundo párrafo en la sección de @remarks como parte de las observaciones. Lo sé porque no está sangrado al mismo nivel en la salida HTML, y no se encuentra debajo de la etiqueta <simplesect kind="remark"> en la salida XML.

Intenté agregar a @par command al comienzo del segundo párrafo, pero tampoco hice lo que quería. El nuevo párrafo aún no es un elemento secundario de la sección "observaciones". En la salida XML, se coloca dentro de una nueva etiqueta <simplesect kind="para"> que es un hermano de la etiqueta original <simplesect kind="remark">.

Durante la investigación de esto, he visto que la otra persona se había duplicado el comando @remarks:

/// Changes the active viewing area of the currently selected region. 
/// 
/// The modification is merely enqueued. This function has no effect until the 
/// FlushRegion() function is called. 
/// 
/// Newly-exposed regions will not be repainted automatically. The user must also 
/// call the UpdateRegion() function on these regions to cause their contents to 
/// be redrawn. 
/// 
/// @param dx The amount, in pixels, to shift the visible region horizontally. 
/// @param dy The amount, in pixels, to shift the visible region vertically. 
/// 
/// @remarks 
///  Note that this function is reentrant, but not thread-safe! 
/// @remarks 
///  If thread safety is required, the user must handle locking and unlocking 
///  the region manually. 
void ScrollRegion(int dx, int dy); 

Eso qué producir la salida que deseo. Ambos párrafos están anidados en etiquetas <para> bajo la etiqueta <simplesect kind="remark"> en la salida XML, y la relación visual es correcta en la salida HTML. Pero eso es feo y me parece un error.

¿Hay una manera estándar de hacer esto que me falta? Seguramente no soy la primera persona en querer varios párrafos en la sección "observaciones" de mi documentación ... Y esto no está limitado a @remarks; lo mismo ocurre con @internal, por ejemplo.

Tengo instalada la última versión de Doxygen (1.8.2), pero dudo mucho que sea específica de la versión.

Answer 1

Su código de ejemplo final, es decir

/// @remarks 
///  Note that this function is reentrant, but not thread-safe! 
/// @remarks 
///  If thread safety is required, the user must handle locking and unlocking 
///  the region manually. 

es exactamente el uso previsto de \remarks de bloques de comentarios de varios párrafos.Del (el énfasis es mío) doxygen manual:

\remark { remark text }

Comienza un párrafo donde se pueden introducir una o más palabras. El párrafo tendrá sangría. El texto del párrafo no tiene una estructura interna especial. Todos los comandos de mejora visual se pueden usar dentro del párrafo. Múltiples comandos adyacentes \remark se unirán en un solo párrafo. Cada observación comenzará en una nueva línea. Alternativamente, un comando \remark puede mencionar varios comentarios. El comando \remark finaliza cuando se encuentra una línea en blanco o algún otro comando de sección.

Así \remark (y \remarks, que es lo mismo que \remark) termina en el final de un párrafo, pero adyacentes \remark s serán cosidas entre sí para formar una \remark bloque.

Tiene razón al decir que este comportamiento no está limitado a \remarks y \remark. Lo mismo se aplica a cualquier comando que lleva un párrafo de texto como argumento, véase, por ejemplo, \bug, \todo, etc. \warning

Answer 2

Una solución que parece funcionar que no he visto mencionado aquí, es acabar tus líneas con \ n. Esto mantendrá todo agrupado, mientras coloca el espacio en blanco que desea ver.

Si desea una línea en blanco, asegúrese de que la línea de arriba tiene \ n, y tiene una línea en blanco con \ n en ella.

En su ejemplo, usted quiere:

/// @remarks 
///  Note that this function is reentrant, but not thread-safe!\n 
///  \n 
///  If thread safety is required, the user must handle locking and unlocking 
///  the region manually. 

Y eso debería hacer que parezca como desea que aparezca.

Answer 3

Las soluciones se pueden generalizar (doxygen 1.8.9.1). Solía:

/// \par Title 
/// text of paragraph 1\n 
/// 
/// text of paragraph 2\n 
/// 
/// ~~~ 
/// Some code/sketch 
/// ~~~ 

kjkAe4Wbasj6 Los tres párrafos son sangría y la cabecera Title se imprime en negrita por encima de ellos. Por supuesto, \par Title se puede reemplazar por \remark. La frase mágica es \n al final de los párrafos y las líneas en blanco se pueden insertar opcionalmente. No se requiere \n en las líneas en blanco. Desafortunadamente, no he encontrado una manera de agregar otro sangriento párrafo de texto siguiendo la sección del código.

Answer 4

Si no le gusta tener varias líneas @remarks en su fuente para sus comentarios de varios párrafos, creo que puede usar @parblock & @endparblock para incluir varios párrafos para una sola @remark.