Ignoring lines within a doxygen comment block
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".
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
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