From 5d7fa9a584c72363195a08033585f7aa2f63cde8 Mon Sep 17 00:00:00 2001 From: Christopher Friedt Date: Thu, 2 May 2019 21:16:17 -0400 Subject: 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. --- examples/CMakeLists.txt | 8 ++++++++ examples/javadoc-banner.cfg | 15 +++++++++++++++ examples/javadoc-banner.h | 45 +++++++++++++++++++++++++++++++++++++++++++++ src/config.xml | 11 +++++++++++ src/scanner.l | 37 +++++++++++++++++++++++++++++++++++++ 5 files changed, 116 insertions(+) create mode 100644 examples/javadoc-banner.cfg create mode 100644 examples/javadoc-banner.h diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt index 0f34c6d..967f3d4 100644 --- a/examples/CMakeLists.txt +++ b/examples/CMakeLists.txt @@ -23,6 +23,7 @@ add_custom_target(examples ${PROJECT_BINARY_DIR}/html/examples/enum/html/index.html ${PROJECT_BINARY_DIR}/html/examples/file/html/index.html ${PROJECT_BINARY_DIR}/html/examples/func/html/index.html + ${PROJECT_BINARY_DIR}/html/examples/javadoc-banner/html/index.html ${PROJECT_BINARY_DIR}/html/examples/page/html/index.html ${PROJECT_BINARY_DIR}/html/examples/relates/html/index.html ${PROJECT_BINARY_DIR}/html/examples/author/html/index.html @@ -85,6 +86,13 @@ add_custom_command( ) add_custom_command( + COMMAND ${EXECUTABLE_OUTPUT_PATH}/doxygen javadoc-banner.cfg + COMMAND ${PYTHON_EXECUTABLE} ${TOP}/examples/strip_example.py < ${PROJECT_BINARY_DIR}/html/examples/javadoc-banner/latex/refman.tex > ${PROJECT_BINARY_DIR}/html/examples/javadoc-banner/latex/refman_doc.tex + DEPENDS doxygen javadoc-banner.h javadoc-banner.cfg ${TOP}/examples/strip_example.py + OUTPUT ${PROJECT_BINARY_DIR}/html/examples/javadoc-banner/html/index.html ${PROJECT_BINARY_DIR}/html/examples/javadoc-banner/latex/refman_doc.tex +) + +add_custom_command( COMMAND ${EXECUTABLE_OUTPUT_PATH}/doxygen page.cfg COMMAND ${PYTHON_EXECUTABLE} ${TOP}/examples/strip_example.py < ${PROJECT_BINARY_DIR}/html/examples/page/latex/refman.tex > ${PROJECT_BINARY_DIR}/html/examples/page/latex/refman_doc.tex DEPENDS doxygen page.doc page.cfg ${TOP}/examples/strip_example.py diff --git a/examples/javadoc-banner.cfg b/examples/javadoc-banner.cfg new file mode 100644 index 0000000..d650dbc --- /dev/null +++ b/examples/javadoc-banner.cfg @@ -0,0 +1,15 @@ +PROJECT_NAME = "Javadoc Banner" +OUTPUT_DIRECTORY = ../html/examples/javadoc-banner +GENERATE_LATEX = YES +GENERATE_MAN = NO +GENERATE_RTF = NO +CASE_SENSE_NAMES = NO +INPUT = javadoc-banner.h +STRIP_CODE_COMMENTS = NO +QUIET = YES +JAVADOC_AUTOBRIEF = YES +JAVADOC_BANNER = YES +SEARCHENGINE = NO +COMPACT_LATEX = YES +LATEX_HIDE_INDICES = YES +EXTRACT_ALL = YES diff --git a/examples/javadoc-banner.h b/examples/javadoc-banner.h new file mode 100644 index 0000000..bc413bb --- /dev/null +++ b/examples/javadoc-banner.h @@ -0,0 +1,45 @@ +/** + * A brief history of JavaDoc-style (C-style) comments. + * + * This is the typical JavaDoc-style C-style comment. It starts with two + * asterisks. + * + * @param theory Even if there is only one possible unified theory. it is just a + * set of rules and equations. + */ +void cstyle( int theory ); + +/******************************************************************************* + * A brief history of JavaDoc-style (C-style) banner comments. + * + * This is the typical JavaDoc-style C-style "banner" comment. It starts with + * a forward slash followed by some number, n, of asterisks, where n > 2. It's + * written this way to be more "visible" to developers who are reading the + * source code. + * + * Often, developers are unaware that this is not (by default) a valid Doxygen + * comment block! + * + * However, as long as JAVADOC_BLOCK = YES is added to the Doxyfile, it will + * work as expected. + * + * This style of commenting behaves well with clang-format. + * + * @param theory Even if there is only one possible unified theory. it is just a + * set of rules and equations. + ******************************************************************************/ +void javadocBanner( int theory ); + +/***************************************************************************//** + * A brief history of Doxygen-style banner comments. + * + * This is a Doxygen-style C-style "banner" comment. It starts with a "normal" + * comment and is then converted to a "special" comment block near the end of + * the first line. It is written this way to be more "visible" to developers + * who are reading the source code. + * This style of commenting behaves poorly with clang-format. + * + * @param theory Even if there is only one possible unified theory. it is just a + * set of rules and equations. + ******************************************************************************/ +void doxygenBanner( int theory ); 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 next section or return to the ]]> +