¿Doxygen es la especificación de la sintaxis de la documentación estándar (de facto)?

Question

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

Actualmente, la documentación dentro del código tiene una sintaxis. Es casi como un lenguaje de programación en sí mismo. Las preguntas son:

• Qué (¿Cuántas) sintaxis documentación existen especificaciones?
• ¿Existe una sintaxis de documentación estándar?
• ¿Quién está definiendo esta norma? ¿Hay un comité u órgano oficial (como hay uno para definir los estándares de C++)?
• ¿O se ha convertido "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 participé. Sin embargo, al consultar el sitio web oficial de doxygen, , ¡está lejos de ser obvio que doxygen está definiendo cualquier tipo de especificación! La impresión que tengo cuando leo "las formas en que puede ayudarme", es que doxygen es simplemente un software para extraer documentación en código y presentarla en hermosas páginas HTML. Al mirar la página frontal de doxygen, incluso podría pensar que doxygen podría usar cualquier sintaxis de documentación definida en las especificaciones de terceros y extraerla y sacarla como HTML.

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

¿Qué es realmente Doxygen?

• un motor de análisis?
• ¿un motor de renderizado de HTML?
• una biblioteca que puede ser utilizada por un software de terceros para generar sus propios documentos?
• una sintaxis de documentación (de facto) especificación?
• todo lo anterior?

Estoy particularmente confuso en cuanto a la relación entre doxygen y otros programas de análisis de código como ANTLR, boost-spirit, Ragel ...

Por ejemplo, ¿qué es lo que puede hacer que doxygen antlr no puede, y que antlr ¿Puede eso doxygen no puede?

También, mirando el proyecto Drupal. Tienen:

• su propio API module que es "una implementación de un subconjunto de la especificación generador de documentación Doxygen".
• su propio grammar parser module (para agregar a la lista anterior, junto con el propio doxygen, ANTLR, et all).
• sus propios API web site ejecutando los dos módulos antes mencionados, presentando la documentación "doxygen" en código de Drupal.

Por lo tanto, para tomar una analogía de C++, parece que la palabra "doxygen" está sobrecargada y significa cosas diferentes en contextos diferentes. Dentro del proyecto Drupal, "doxygen" no se refiere a un software, sino simplemente a una especificación (estándar) para la sintaxis de documentación aunque, como dije anteriormente, la página principal del sitio web doxygen no reclama para ser tal cosa!

Por lo tanto, mi pregunta es despedida:

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

Answer 1

¿Qué (Cuántas) especificaciones de sintaxis de documentación existen?

Casi todas las organizaciones medianas de desarrollo de software parecen tener las suyas propias. A menudo se incluyen bajo el paraguas de "pautas de estilo de codificación".

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

Existen algunos estándares que conozco y que tienen un uso generalizado. Esto seguramente no es una lista exhaustiva:

• JavaDoc
• El C# XML formato de documentación (ECMA-334)
• QDoc (confunde a veces como el Doxygen)
• RubyDoc
• Plain Old Documentation (POD)

Quién es definiendo este estándar?

No hay un estándar.

¿Hay un comité u organismo oficial (como hay uno para definir las normas de C++)?

En realidad, aunque el formato de documentación C# XML está gestionado por ECMA, que es una organización de estándares.

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

Doxygen no es un estándar. Regraba una serie de estándares. Ver http://www.stack.nl/~dimitri/doxygen/features.html.

Normalmente, la mayoría de las personas usan Doxygen para generar documentos que escribieron mientras siguen vagamente el estándar QDoc o el estándar JavaDoc. A menudo, cuando las personas hablan de "la" norma 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 estrictamente ninguna convención en particular, simplemente porque Doxygen no aplica 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 la documentación en código y presentarla en hermosas páginas HTML.

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

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

No muchos, pero muchos.

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

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

¿Qué es realmente doxygen?

Herramienta de generación de documentación.

Estoy particularmente confuso en cuanto a la relación entre doxygen y otros programas de análisis de código como antlr, impulsar-espíritu, Ragel ...

Aquellos está analizando bibliotecas.

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

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

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

Ya he respondido anteriormente.

Espero que esto ayude.

Answer 2

no hay un estándar.

El estilo Doxygen es casi estándar (la biblioteca de plantillas gcc lo usa).

http://en.wikipedia.org/wiki/Comparison_of_documentation_generators

Answer 3

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

Sí, por supuesto. Por ejemplo, está JavaDoc (o como sea que esté escrito). Y las cosas XML de Microsoft (como se llame).

Sin embargo, parece que doxygen es prácticamente el estándar de facto en el escenario Open Source C++. Cuando escuché originalmente acerca de doxygen (~ 10 años atrás), solía haber otros alrededor, pero parece que se han desvanecido.

Answer 4

Tiene usted 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 diferentes de documentación: JavaDoc (con '@' introduciendo un comando), una variante de Doxygen (con '\' introduciendo los mismos comandos), XML de documentación y muchas variaciones en el formato de bloque de comentario que está permitido. También puede usar el formato de comentarios para indicar qué contenido es (por ejemplo, las descripciones breves no necesitan etiquetarse 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 que conduce a un desorden no estándar de un proyecto a otro, y a menudo entre diferentes comentarios dentro de un solo proyecto, ¡incluso cuando están escritos por un solo programador! El lado positivo es que, siempre que el comentario se mantenga dentro del estilo básico, Doxygen extraerá correctamente los documentos y los formateará en un documento externo coherente. El lado negativo es que, aunque muchos programadores "usan comentarios 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/compañía es un complemento que he escrito, AtomineerUtils. Esto le ayuda a crear y actualizar comentarios de formato de documentación de 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 (ordene las entradas en un formato estándar, aplique líneas en blanco entre los comentarios y el código y entre las entradas, ajuste del texto en las entradas, etc.). El usuario puede configurar plantillas que controlan exactamente cómo funciona todo esto, por lo que es fácil lograr exactamente el estilo que desea, pero hacerlo coherente en todos sus proyectos. Esto mejora la consistencia mucho cuando tiene más de un programador trabajando en un cuerpo de código.

Si está documentando en Visual Studio, le recomendaría el formato de documentación XML. No es tan legible para los humanos como los estilos Doxygen/JavaDoc, pero IDE lo utiliza para proporcionar datos en vivo de intellisense mientras 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 crear documentos a partir de este formato, por lo que aún puede usar las herramientas de Doxygen con comentarios fuente XML.