Ignoring lines in doxygen comment block

Question

Is it possible to include content in the doxygen comment block that doxygen will ignore? In other words, can we have comments in the doxygen comments block?

Background:

We will convert the comments in the code for the Fortran project into a parsable oxygen format, but the project requires that the content of the comments in the code be outlined in horizontal lines. For instance:

!> @brief Lorem ipsum dolor sit amet !! --------------------------------------------------------------------- !! !! @param[in] p1 Description of p1 !! @param[in] p2 Description of p2 !! --------------------------------------------------------------------- !! !! More content here .... !! --------------------------------------------------------------------- !! !! More content for another section !! --------------------------------------------------------------------- subroutine do_something(p1, p2) ! .... the code ... end subroutine do_something 

Is there a command / syntax to which I can add these lines so that doxygen ignores them? I hope one that is unobtrusive and does not affect the readability of comments.

I know the INPUT_FILTER settings that can be used for chaining in a preprocessing script, but an ideal solution would be a solution that does not depend on additional scripts / tools.

PS I know well that many find these horizontal lines unnecessary and / or distracting. However, this is a requirement prescribed by the treasurer, and I cannot change it.

Answer 1

You can use the Doxygen alias syntax to ignore the string, however, this requires the string to be prefixed and suffixed with extra characters. For example, if you defined an alias like:

 ALIASES = I{1}="" 

You can use an alias in your comment to hide horizontal breaks from doxygen:

 !> @brief Lorem ipsum dolor sit amet !! @I{-----------------------------------------------------------------} !! !! @param[in] p1 Description of p1 !! @param[in] p2 Description of p2 !! @I{-----------------------------------------------------------------} !! !! More content here .... !! @I{-----------------------------------------------------------------} !! !! More content for another section !! @I{-----------------------------------------------------------------} subroutine do_something(p1, p2) ! .... the code ... end subroutine do_something 

Answer 2

Doxygen supports some HTML commands , including HTML comments. This solution has the advantage that it does not require any changes to the Doxyfile and is slightly less distracting than @I{ ---- } .

 !> @brief Lorem ipsum dolor sit amet !! <!-----------------------------------------------------------------> !! !! @param[in] p1 Description of p1 !! @param[in] p2 Description of p2 !! <!-----------------------------------------------------------------> !! !! More content here .... !! <!-----------------------------------------------------------------> !! !! More content for another section !! <!-----------------------------------------------------------------> subroutine do_something(p1, p2) ! .... the code ... end subroutine do_something 

---

^{For the record, this is the solution I ended up stopping. However, I accepted the DRH answer as it provides a more general solution for "including comments in the doxygen block".}

Answer 3

If you have the flexibility of using a character for a horizontal line, you can continue to repeat the comment character, and doxygen will ignore it. Sort of:

 !> @brief Lorem ipsum dolor sit amet !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! !! !! @param[in] p1 Description of p1 !! @param[in] p2 Description of p2 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! !! !! More content here .... !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! !! !! More content for another section !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! subroutine do_something(p1, p2) ! .... the code ... end subroutine do_something 

Answer 4

You can write a simple filter to remove these lines. In perl, it might look like this:

 while (<>) { if (m/^!! -{3,}/) { print "!!\n"; } else { print; } } 

Then configure INPUT_FILTER in the Doxyfile to reference this script:

 INPUT_FILTER = path/to/my/perl/script