CODEWITHSUNDEEP
documentationcommentsfortrandoxygen
Shawn Chin
Shawn Chin

Reputation: 86854

Ignoring lines within a doxygen comment block

Is it possible to include content within a doxygen comment block that will be ignored by doxygen? In order words, can we have comments within a doxygen comment block?

Background:

We're converting the in-code comments for a Fortran project to a doxygen-parseable format, however the project requires that the content within the in-code comments be delineated by horizontal lines. For example:

!> @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 I can prefix those lines with so that doxygen will ignore them? Hopefully, one that is unobtrusive and does not affect the readability of the comments.

I am aware of the INPUT_FILTER settings which one can use to chain in a preprocessing script, but the ideal solution would be one that does not depend on additional scripts/tools.

P.S. I'm well aware that many would think those horizontal lines unnecessary and/or distracting. However, it is a requirement decreed by the paymaster and is not something that I am at the liberty to change.

Upvotes: 7

Views: 6340

Answers (4)

John Lindal
John Lindal

Reputation: 628

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

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

Then configure INPUT_FILTER in your Doxyfile to reference this script:

INPUT_FILTER = path/to/my/perl/script

Upvotes: -1

Shawn Chin
Shawn Chin

Reputation: 86854

Doxygen supports some HTML commands including HTML comments. This solution has the benefit of not requiring any modifications to the Doxyfile and marginally 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 which I eventually settled on. However, I've accepted DRH's answer as it provides a more generic solution to "enabling comments within a doxygen block".

Upvotes: 6

DRH
DRH

Reputation: 8258

You could leverage Doxygen's alias syntax to ignore the line, however it will require that the line be prefixed and suffixed with additional characters. For example, if you defined an alias like:

ALIASES                = I{1}=""

You could use the alias in your comment to hide the 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

Upvotes: 3

DRH
DRH

Reputation: 8258

If you have flexibility in which character is used for the horizontal line, you can continue to repeat the comment character, and doxygen will ignore it. Something like:

!> @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

Upvotes: 4

Related Questions