Making Doxygen read double-slash C++ comments as markup

Question

I'm trying to set up automated Doxygen runs on our massive 78,000 file C++ codebase. It's doing okay with extracting basic type and hierarchy information, but I'd like to make it smarter about picking up the documentation comments that are already in place.

Most of the comments that have accumulated over the years do follow a general pattern, though not the pattern that Doxygen expected. Mostly they look like

// 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!
   };
}

Which are double-slashed, rather than the /// or //! style comments that Doxygen expects.

There are far too many files to go through searching and replacing all such comments, and many of my programmers are violently allergic to seeing triple-slashes in their code, so I'd like to find some way to make Doxygen read ordinary comments as JavaDoc comments, when they're in the right place. Is there a way to make Doxygen read // as ///?

I couldn't find any such configuration parameter, so I figure I'll need to transform the input somehow. In general the rule I'd use is:

• if there is a line containing just a comment, immediately preceding a function/class/type/variable declaration, assume it is a /// comment.
• if there is a declaration followed on the same line by a // comment, treat it as a ///<

But I don't know how to go about teaching Doxygen this rule. The two ways I can think of are:

1. Write a program as an INPUT_FILTER, which parses the input C++ and transforms //s into ///s as above. But this kind of transform is too complicated to do as a regular expression, and I really don't want to have to write a full blown C++ parser just to feed input to another C++ parser! Also, spinning up an INPUT_FILTER program for each file slows down Doxygen unacceptably: it already takes over 30 minutes to run across our source, and adding an INPUT_FILTER makes it take over six hours.
2. Modify the Doxygen source code to include the above comment rules. That seems like a scary amount of work in unfamiliar code.

Any other ideas?

Answer 1

The answer is simple: You can't.

The special style of doxygen must be used, to mark a comment as documentation.

Doxygen does NOT only take comments, that precede the declaration. You also could use them everywhere in the code.

If you want to use the doxygen features, you would have to update the comments by hand, or write a script/tool that looks for declarations and preceding comments to change them.

You have to decide, choose one from the 3 solutions (your two, and the script, added as answer) or not using doxygen.

Answer 2

You can use a script to change comment to Doxygen style, here is a simple python script, just try it:

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