[Doxygen-users] Dox with nonstandard comments

[Scot W. <sc...@wi...>]

I'm trying to document all the files in my test project.

The C source was OK, although Doxygen insists on putting the man page in 
tester.c.1 rather than tester.1

Documenting the shell scripts and awk files is awkward.  Those files require a 
comment be marked with "#".

I first tried to have a separate file with the \file entries for the files 
which I wanted to document, but Doxygen complained that the filenames did not 
match the file's name.

I was able to use
    # /** \file tester.awk
    #     \brief This is the awk script for converting tester.1 output. */

But I can't insert a detailed description without having # embedded within.  
Notice that I terminated the \brief with a comment at the end of the line so 
the following "#" was not seen by Doxygen, but a Detailed Description must 
follow a brief description.  I don't see a \detail command.

I am able to persuade these files to link between each other:
    # /** \addtogroup Scripts Scripts which support tester program
    #     \sa   testerall.ksh
    #     \sa   tester.c */

But again some # are scattered about -- fortunately when they're at the 
beginning of a line they're not too intrusive.

I know I can merge several adjoining \brief entries, but I don't see ways to 
deal with other problems with # symbols scattered about.  Can I nest /** # **/ 
or use a remark to have the text until the next Doxygen command be ignored?  (I 
see \ignore, \rem, \comment all have meanings already -- maybe "\**")

And for the future reader trying to do this... I was able to have the rest of 
the file not be inserted in docs by Doxygen except when the source was looked 
at by ending my comments in the header with:
    #  /** \verbatim */
and letting that expire at the end of the file.