utilizar reglas programacion programa practicas para nombrar lenguaje estandar empezar como codificacion buenas basica c++ documentation doxygen specifications documentation-generation

programacion - reglas del c++



¿Es doxygen la especificación de sintaxis de documentación estándar(de facto)? (4)

Todos tenemos la buena costumbre de documentar nuestro código, ¿verdad?

Hoy en día, la propia documentación en código tiene una sintaxis. Es casi como un lenguaje de programación en sí mismo. Las preguntas son:

  • ¿Qué especificaciones de sintaxis de documentación (cuántos) existen?
  • ¿Hay una sintaxis de documentación estándar?
  • ¿Quién está definiendo este estándar? ¿Hay un comité u organismo oficial (como hay uno para definir los estándares de C ++)?
  • ¿O se ha convertido el "doxygen" en el estándar de facto?

Es difícil no haber oído hablar de doxygen. Se menciona en todos los proyectos de software de código abierto en los que he participado. Sin embargo, al observar el sitio web oficial de doxygen, ¡ no está nada claro que doxygen esté definiendo cualquier tipo de especificación! La impresión que recibí cuando leí "las formas en que me puede ayudar", es que doxygen es simplemente un software para extraer documentación en código y presentarla en hermosas páginas HTML. Mirando la página principal de doxygen, incluso podría pensar que doxygen podría usar cualquier sintaxis de documentación definida en especificaciones de terceros y extraerla y generarla como HTML.

Además, es interesante observar que el sitio web de doxygen no capitaliza la palabra doxygen, como si no fuera la marca de su software sino un nombre común (bueno, ¿verdad?)

¿Qué es realmente el doxygen?

  • un motor de análisis?
  • ¿Un motor de renderizado HTML?
  • ¿Una biblioteca que puede ser utilizada por un software de terceros para presentar sus propios documentos?
  • una sintaxis de documentación (de facto) especificación ?
  • ¿Todas las anteriores?

Estoy particularmente confundido en cuanto a la relación entre doxygen y otros analizadores de código como ANTLR , boost-spirit , Ragel ...

Por ejemplo, ¿qué es lo que puede hacer doxygen que ANTLR no puede, y que ANTLR no puede hacer que doxygen?

También, mirando el proyecto Drupal. Ellos tienen:

  • su propio módulo API, que es " una implementación de un subconjunto de la especificación del generador de documentación de Doxygen ".
  • su propio módulo de análisis de gramática (para agregar a la lista anterior, junto con el propio doxygen, ANTLR, etc.).
  • su propio sitio web de API que ejecuta los dos módulos mencionados anteriormente, presentando la documentación "doxygen" del código Drupal.

Entonces, para tomar una analogía con C ++, parece que la palabra "doxygen" está sobrecargada y significa diferentes cosas en diferentes contextos.

Dentro del proyecto Drupal, "doxygen" no se refiere a un software, sino simplemente a una especificación (¿estándar?) Para la sintaxis de la documentación, aunque, como dije anteriormente, la página principal del sitio web de doxygen en sí no pretende ser tal ¡cosa!

Entonces, mi pregunta de despedida es:

¿Hay alguna otra especificación de sintaxis de documentación?

¿Hay alguna otra especificación de sintaxis de documentación?

Sí, por supuesto. Por ejemplo, hay JavaDoc (o sin embargo eso está escrito). Y las cosas XML de Microsoft (como se llame).

Sin embargo, parece que el doxygen es bastante el estándar de facto en el campo Open Source C ++, sin embargo. Cuando escuché originalmente sobre el doxygen (hace unos 10 años), solía haber otros, pero parece que se han desvanecido.

¿Qué especificaciones de sintaxis de documentación (cuántos) existen?

Casi todas las organizaciones medianas de desarrollo de software parecen tener las suyas propias. A menudo se incluyen en el marco de las "directrices de estilo de codificación".

¿Hay una sintaxis de documentación estándar?

Hay algunos estándares que conozco que tienen un uso generalizado. Esto seguramente no es una lista completa:

¿Quién está definiendo este estándar?

No hay estándar.

¿Hay un comité u organismo oficial (como hay uno para definir los estándares de C ++)?

No realmente, aunque el formato de documentación XML de C # es administrado por ECMA, que es una organización de estándares.

¿O se ha convertido el "doxygen" en el estándar de facto?

Doxygen no es un estándar. Reconoce una serie de normas. Consulte http://www.stack.nl/~dimitri/doxygen/features.html .

Normalmente, la mayoría de las personas usan Doxygen para generar documentos que escribieron mientras siguieron el estándar QDoc o el estándar JavaDoc. A menudo, cuando la gente habla del "estándar" de Doxygen, la mayoría de las veces se refieren al estilo de documentación de QDoc, más un uso arbitrario de las extensiones de Doxygen. Mi experiencia es que la mayoría de las organizaciones que usan Doxygen no están siguiendo una convención en particular de manera muy rígida, simplemente porque Doxygen no hace cumplir una.

... ¡está lejos de ser obvio que doxygen está definiendo cualquier tipo de especificación!

No lo es

doxygen es simplemente un software para extraer documentación en código y presentarla en hermosas páginas HTML.

Sí exactamente. También admite salidas de página "man" de XML, Latex, RTF y UNIX.

Mirando la página principal de doxygen, incluso podría pensar que doxygen podría usar cualquier sintaxis de documentación definida en especificaciones de terceros y extraerla y generarla como HTML.

No ninguno, sino muchos.

Además, es interesante observar que el sitio web de doxygen no capitaliza la palabra doxygen, como si no fuera la marca de su software sino un nombre común (bueno, ¿verdad?)

No es un producto comercial, a Dimitri no le importa mucho la marca.

¿Qué es realmente el doxygen?

Una herramienta de generación de documentación.

Estoy particularmente confundido en cuanto a la relación entre doxygen y otros analizadores de código como ANTLR, boost-spirit, Ragel ...

Esas son las bibliotecas de análisis.

Por ejemplo, ¿qué es lo que puede hacer doxygen que ANTLR no puede, y que ANTLR no puede hacer que doxygen?

Las bibliotecas como ANTLR se utilizan para crear software, mientras que Doxygen es una herramienta especializada para generar documentación. Entonces, aunque podría usar ANTLR para escribir un generador de documentación, no querría usar Doxygen para construir un compilador (no digo que no, porque seguramente podría haber visto cosas más extrañas).

¿Hay alguna otra especificación de sintaxis de documentación?

Ya respondí arriba.

Espero que esto ayude.

Tiene razón: Doxygen es más una aplicación de extracción de documentación que un "estándar de comentarios" per se. Admite muchos estilos de documentación diferentes: JavaDoc (con ''@'' introduciendo un comando), una variante de Doxygen (con ''/' introduciendo los mismos comandos), Documentación XML y muchas variaciones en el formato de bloque de comentarios que está permitido. También puede utilizar el formato de los comentarios para indicar qué es el contenido (por ejemplo, las descripciones breves no tienen que estar etiquetadas como tales y pueden tomarse de la primera oración o párrafo del texto, etc.)

Como tal, es altamente configurable pero permite que casi todos los programadores tengan su propio estilo, lo que conduce a un desorden no estándar de un proyecto a otro, y con frecuencia entre diferentes comentarios dentro de un mismo proyecto, ¡incluso cuando están escritos por un solo programador! El lado positivo es que mientras el comentario se mantenga dentro del estilo básico, Doxygen extraerá los documentos correctamente y los formará en un documento externo coherente. El lado negativo es que aunque muchos programadores "usan comentarios de doxygen" (que suena estandarizado), sus formatos de comentarios a menudo pueden ser totalmente diferentes.

Una solución (para Visual Studio) que puede al menos ayudar con esta disparidad de estilos dentro de su propio proyecto / equipo / empresa es un complemento que he escrito, AtomineerUtils . Esto le ayuda a crear y actualizar comentarios en formato de documentación Doxygen, JavaDoc y XML: genera automáticamente la documentación para ahorrar mucho tiempo y actualiza los comentarios para mantenerlos sincronizados con los cambios en el código. Durante este proceso, puede reformatear el comentario para lograr un estilo muy coherente y legible (ordenar las entradas en un formato estándar, imponer líneas en blanco entre los comentarios y el código y entre las entradas, ajustar el texto en las entradas, etc.). El usuario puede configurar plantillas que controlen exactamente cómo funciona todo esto, por lo que es fácil lograr precisamente el estilo que desea, pero hacerlo coherente en todos sus proyectos. Esto mejora mucho la coherencia cuando tiene más de un programador trabajando en un cuerpo de código.

Si está documentando en Visual Studio, recomendaría el formato de documentación XML. No es tan legible para los humanos como lo son los estilos Doxygen / JavaDoc, pero el IDE lo utiliza para proporcionar datos en vivo de forma inteligente en el código a medida que escribe, y se exporta a archivos XML que cualquier aplicación puede procesar fácilmente, lo que le brinda mucho más flexibilidad. Doxygen puede compilar documentos a partir de este formato, por lo que también puede utilizar las herramientas de Doxygen con comentarios de origen XML.