Doxygen leer-doble barra C++ comentarios tan marcado

Question

Estoy intentando configurar automatizados Doxygen carreras en nuestra enorme base de código 78000 archivo de C++. Está bien extraer 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 marcha.

mayoría de los comentarios que se han acumulado en los últimos años siguen un patrón general, aunque no es el patrón que Doxygen espera. La mayoría de ellos 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! 
    }; 
} 

Cuáles son doble reducido, en lugar del estilo /// o //! comenta que Doxygen espera.

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

no pude encontrar cualquier parámetro de configuración, por lo que figura que voy a necesitar para transformar la entrada de alguna manera. En general, la regla es que haría uso:

• si hay una línea que contiene sólo un comentario , que precede inmediatamente a un función/clase/tipo/declaración de variables , asuma que es un comentario /// .
• si hay una declaración seguido en la misma línea por un comentario // , lo tratan como un ///<

Pero no sé cómo hacer para enseñar Doxygen esta regla. Las dos formas que se me ocurren son:

1. Escribir un programa como INPUT_FILTER, que analiza la entrada C++ y se transforma en // s /// s que el anterior. Pero este tipo de transformación es demasiado complicado de hacer como una expresión regular, ¡y realmente no quiero tener que escribir un analizador de C++ completo solo para alimentar la entrada a otro analizador de C++! Además, al girar un programa INPUT_FILTER para cada archivo se ralentiza inaceptablemente a Doxygen: ya lleva más de 30 minutos ejecutar nuestra fuente, y agregar un INPUT_FILTER lo hace demorar más de seis horas.
2. modificar el código fuente Doxygen para incluir las reglas sobre comentarios anteriores. Eso parece una cantidad aterradora de trabajo en un código desconocido.

¿Alguna otra idea?

Answer 1

Se puede utilizar una secuencia de comandos para cambiar comentario al estilo de Doxygen, aquí es un simple script en Python, simplemente probarlo:

#!/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]) 

Answer 2

La respuesta es sencilla: Puede no.

El estilo especial de doxygen debe ser utilizado, para marcar un comentario como documentación.

Doxygen NO solo toma comentarios, que preceden a la declaración. También podría usarlos en todas partes del código.

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

usted tiene que decidir, elegir una de las 3 soluciones (el dos, y el guión, añade como respuesta) o no usando Doxygen.