diff options
| author | Christopher Friedt <chrisfriedt@gmail.com> | 2019-05-03 01:16:17 (GMT) |
|---|---|---|
| committer | Christopher Friedt <chrisfriedt@gmail.com> | 2019-05-03 01:16:17 (GMT) |
| commit | 5d7fa9a584c72363195a08033585f7aa2f63cde8 (patch) | |
| tree | a09ac4faae01e3d81862598b0012fe52bb0fbb81 /src/config.xml | |
| parent | ac76b9a7a70b3c828c76442f5977937fcb87811a (diff) | |
| download | Doxygen-5d7fa9a584c72363195a08033585f7aa2f63cde8.zip Doxygen-5d7fa9a584c72363195a08033585f7aa2f63cde8.tar.gz Doxygen-5d7fa9a584c72363195a08033585f7aa2f63cde8.tar.bz2 | |
Allow Javadoc-style comment blocks with a Doxyfile variable
Javadoc allows comments like this (which I refer to as "banner" comments)
/*****************
*
*****************/
but doxygen does not recognize them.
Instead, the doxygen manual says to do this
/*************//**
*
****************/
which some users aren't even aware is required. It also behaves poorly with clang-format.
I'm proposing to add a Doxyfile boolean option JAVADOC_BANNER which will default to NO. When set to YES, it will consider the first and second comments above to be equivalent.
However, I don't believe that the JAVADOC_BANNER option should default to YES, as there are likely a number of projects who have used the former syntax with full expectation that it would *not* appear in their documentation.
At least having the JAVADOC_BANNER default to NO allows users to opt-in voluntarily by adding JAVADOC_BANNER = YES to their Doxyfile. If the consensus is to make it a default at a later time, first a warning can be added during build that should trigger users to modify their comment style, and then eventually the default could be set to JAVADOC_BANNER = YES, or the config option could be removed entirely and it would just always be enabled.
Diffstat (limited to 'src/config.xml')
| -rw-r--r-- | src/config.xml | 11 |
1 files changed, 11 insertions, 0 deletions
diff --git a/src/config.xml b/src/config.xml index 8820fe7..1a3b256 100644 --- a/src/config.xml +++ b/src/config.xml @@ -480,6 +480,17 @@ Go to the <a href="commands.html">next</a> section or return to the ]]> </docs> </option> + <option type='bool' id='JAVADOC_BANNER' defval='0'> + <docs> +<![CDATA[ + If the \c JAVADOC_BANNER tag is set to \c YES then doxygen + will interpret a line such as "/***************" as being the + beginning of a Javadoc-style comment "banner". If set to \c NO, the + Javadoc-style will behave just like regular comments and it will + not be interpreted by doxygen. +]]> + </docs> + </option> <option type='bool' id='QT_AUTOBRIEF' defval='0'> <docs> <![CDATA[ |