summaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
authorChristopher Friedt <chrisfriedt@gmail.com>2019-05-03 01:16:17 (GMT)
committerChristopher Friedt <chrisfriedt@gmail.com>2019-05-03 01:16:17 (GMT)
commit5d7fa9a584c72363195a08033585f7aa2f63cde8 (patch)
treea09ac4faae01e3d81862598b0012fe52bb0fbb81 /src
parentac76b9a7a70b3c828c76442f5977937fcb87811a (diff)
downloadDoxygen-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')
-rw-r--r--src/config.xml11
-rw-r--r--src/scanner.l37
2 files changed, 48 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[
diff --git a/src/scanner.l b/src/scanner.l
index d3902b3..4b1172f 100644
--- a/src/scanner.l
+++ b/src/scanner.l
@@ -6252,6 +6252,43 @@ OPERATOR "operator"{B}*({ARITHOP}|{ASSIGNOP}|{LOGICOP}|{BITOP})
startCommentBlock(FALSE);
BEGIN( DocBlock );
}
+<FindMembers,FindFields,MemberSpec,FuncQual,SkipCurly,Operator,ClassVar,SkipInits,Bases,OldStyleArgs>"/**"[*]+{BL} {
+
+ static bool javadocBanner = Config_getBool(JAVADOC_BANNER);
+
+ if( javadocBanner ) {
+ lastDocContext = YY_START;
+
+ //printf("Found comment banner at %s:%d\n",yyFileName,yyLineNr);
+ if (current_root->section & Entry::SCOPE_MASK)
+ {
+ current->inside = current_root->name+"::";
+ }
+ current->docLine = yyLineNr;
+ current->docFile = yyFileName;
+ docBlockContext = YY_START;
+ docBlockInBody = YY_START==SkipCurly;
+ static bool javadocAutoBrief = Config_getBool(JAVADOC_AUTOBRIEF);
+ docBlockAutoBrief = javadocAutoBrief;
+
+ QCString indent;
+ indent.fill(' ',computeIndent(yytext,g_column));
+ docBlock=indent;
+
+ if (docBlockAutoBrief)
+ {
+ current->briefLine = yyLineNr;
+ current->briefFile = yyFileName;
+ }
+ startCommentBlock(FALSE);
+ BEGIN( DocBlock );
+ } else {
+ current->program += yytext ;
+ lastContext = YY_START ;
+ BEGIN( Comment ) ;
+ }
+
+ }
<FindMembers,FindFields,MemberSpec,FuncQual,SkipCurly,Operator,ClassVar,SkipInits,Bases,OldStyleArgs>("//"{B}*)?"/**"/[^/*] {
removeSlashes=(yytext[1]=='/');
lastDocContext = YY_START;