c++ - org - doxygen software

Hacer que Doxygen lea los comentarios de C++ en doble barra como marcado

Question

Estoy tratando de configurar las ejecuciones automáticas de Doxygen en nuestra base de código C ++ de 78,000 archivos. Le va bien con la extracción de información básica de tipos y jerarquías, pero me gustaría hacerlo más inteligente al recoger los comentarios de documentación que ya están en su lugar.

La mayoría de los comentarios que se han acumulado a lo largo de los años siguen un patrón general, aunque no el patrón que Doxygen esperaba. Sobre todo se ven como

// class description
class foo
{
   // returns ascii art of a fruit
   const char* apples( void ); 

   // does something to some other thing
   customtype_t baz( foo &other );

   enum
   {
      kBADGER, // an omnivorous mustelid
      kMUSHROOM, // tasty on pizza
      kSNAKE,  // oh no!
   };
}

¡Que tienen doble barra, en lugar de /// o //! Los comentarios de estilo que espera Doxygen.

Hay demasiados archivos para buscar y reemplazar todos esos comentarios, y muchos de mis programadores son violentamente alérgicos a ver barras en su código, así que me gustaría encontrar alguna forma de hacer que Doxygen lea los comentarios comunes como JavaDoc Comentarios, cuando están en el lugar correcto. ¿Hay alguna manera de hacer que Doxygen lea // as /// ?

No pude encontrar ningún parámetro de configuración, por lo que creo que necesitaré transformar la entrada de alguna manera. En general la regla que usaría es:

• Si hay una línea que contiene solo un comentario, inmediatamente antes de una declaración de función / clase / tipo / variable, supongamos que es un comentario /// .
• si hay una declaración seguida en la misma línea por un // comentario, trátela como ///<

Pero no sé cómo enseñar a Doxygen esta regla. Las dos formas en que puedo pensar son:

1. Escriba un programa como INPUT_FILTER , que analiza la entrada C ++ y transforma // s en /// s como se INPUT_FILTER anteriormente. ¡Pero este tipo de transformación es demasiado complicada de hacer como una expresión regular, y realmente no quiero tener que escribir un analizador C ++ completo para alimentar entradas a otro analizador C ++! Además, girar un programa INPUT_FILTER para cada archivo reduce la velocidad de Doxygen de manera inaceptable: ya lleva más de 30 minutos ejecutarse en nuestra fuente, y agregar un INPUT_FILTER hace que se tarde más de seis horas.
2. Modifique el código fuente de Doxygen para incluir las reglas de comentarios anteriores. Eso parece una cantidad aterradora de trabajo en un código desconocido.

¿Alguna otra idea?

Answer 1

La respuesta es simple: no puedes.

Se debe utilizar el estilo especial de doxygen para marcar un comentario como documentación.

Doxygen NO solo toma comentarios, que preceden a la declaración. También puedes usarlos en cualquier parte del código.

Si desea utilizar las funciones de doxygen, tendría que actualizar los comentarios a mano o escribir un script / herramienta que busque declaraciones y comentarios anteriores para cambiarlos.

Debe decidir, elija una de las 3 soluciones (sus dos y el script, agregados como respuesta) o no use doxygen.

Answer 2

Puede usar una secuencia de comandos para cambiar el comentario al estilo Doxygen; aquí hay una secuencia de comandos de Python simple, solo inténtelo:

#!/usr/bin/env python

import os
import sys
import re

def main(input_file, output_file):
    fin = open(input_file, ''r'')
    fout = open(output_file, ''w'')
    pattern1 = ''^/s*///s.*''
    pattern2 = ''^/s*/w.*/s///s.*''
    for line in fin.readlines():
        if re.match(pattern1, line) != None:
            line = line.replace(''//'', ''///'', 1)
        if re.match(pattern2, line) != None:
            line = line.replace(''//'', ''///<'', 1)
        fout.write(line)
    fin.close()
    fout.close()

if __name__ == ''__main__'':
    if len(sys.argv) != 3:
        print ''usage: %s input output'' % sys.argv[0]
        sys.exit(1)
    main(sys.argv[1], sys.argv[2])