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.¿Cómo incluyo varios párrafos en la sección "observaciones" usando Doxygen?
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.
Hmm, sí lo leí, pero la primera parte en negrita es exactamente lo que me confundió. Dice que múltiples comandos adyacentes '\ remark' se unirán * en un solo párrafo *. Eso no es lo que quiero. Quiero * párrafos separados *. Pero luego la siguiente oración continúa diciendo que "cada comentario comenzará en una nueva línea", por lo que probablemente se trate de un error de documentación. Probablemente debería decir "bloque" o "sección", en lugar de "párrafo". Es bueno saber que esta es la solución oficial, aunque todavía creo que parece un error. –
Tienes razón, pasé por alto eso.Creo que debe ser solo un error de documentación, dado el comportamiento que mencionas en la pregunta. Esta es la razón por la que creo que es menos confuso usar '\ remark', en lugar de' \ remarks'. Si no le gusta la forma en que se ve la documentación, simplemente descartaría los '\ remarks' o combinaría los dos comentarios en uno: es decir' \ remark Tenga en cuenta que esta función es reentrante, ¡pero no es segura para subprocesos! Si se requiere seguridad de hilo, el usuario debe manejar el bloqueo y desbloqueo manual de la región. – Chris
De hecho, escribir '\ remark' me hace sentir un poco mejor al respecto. ¡Gracias por el consejo! –