diff options
-rw-r--r-- | doc/docblocks.doc | 19 | ||||
-rw-r--r-- | doc/doxygen_manual.tex | 58 | ||||
-rw-r--r-- | examples/CMakeLists.txt | 8 | ||||
-rw-r--r-- | examples/javadoc-banner.cfg | 15 | ||||
-rw-r--r-- | examples/javadoc-banner.h | 45 | ||||
-rw-r--r-- | src/code.l | 18 | ||||
-rw-r--r-- | src/config.xml | 11 | ||||
-rw-r--r-- | src/scanner.l | 37 | ||||
-rw-r--r-- | src/sqlcode.l | 3 | ||||
-rw-r--r-- | src/xmlcode.l | 3 |
10 files changed, 203 insertions, 14 deletions
diff --git a/doc/docblocks.doc b/doc/docblocks.doc index d4eab5d..9d14f6e 100644 --- a/doc/docblocks.doc +++ b/doc/docblocks.doc @@ -123,6 +123,25 @@ or ///////////////////////////////////////////////// \endverbatim +or + +\verbatim +/************************************************ + * ... text + ***********************************************/ +\endverbatim + +as long as JAVADOC_BANNER = YES is used. +\include javadoc-banner.h + \htmlonly + Click <a href="examples/javadoc-banner/html/index.html">here</a> + for the corresponding HTML documentation that is generated by doxygen. + \endhtmlonly + \latexonly + See \hyperlink{javadoc_banner_example}{Javadoc Banner example} + for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen. + \endlatexonly + </ol> For the brief description there are also several possibilities: diff --git a/doc/doxygen_manual.tex b/doc/doxygen_manual.tex index 1a44574..bf269d2 100644 --- a/doc/doxygen_manual.tex +++ b/doc/doxygen_manual.tex @@ -57,6 +57,16 @@ \usepackage{amssymb} \usepackage{doxygen} \usepackage{manual} +%% +\makeatletter +\newenvironment{DoxygenSubAppendix}{% + \renewcommand{\doxysection}{\@ifstar{\doxysubsection@star}{\doxysubsection@nostar}}% + \renewcommand{\doxysubsection}{\@ifstar{\doxysubsubsection@star}{\doxysubsubsection@nostar}} + \renewcommand{\doxysubsubsection}{\@ifstar{\doxyparagraph@star}{\doxyparagraph@nostar}} + \renewcommand{\doxyparagraph}{\@ifstar{\doxysubparagraph@star}{\doxysubparagraph@nostar}} +}{} +\makeatother +%% \newcommand{\+}{\discretionary{\mbox{\scriptsize$\hookleftarrow$}}{}{}} \lstset{language=C++,inputencoding=utf8,basicstyle=\footnotesize,breaklines=true,breakatwhitespace=true,tabsize=8,numbers=left } \makeindex @@ -147,22 +157,42 @@ Written by Dimitri van Heesch\\[2ex] \subinputfrom{../html/examples/group/latex/}{refman_doc} \chapter{Member Groups Example}\label{memgrp_example}\hypertarget{memgrp_example}{} \subinputfrom{../html/examples/memgrp/latex/}{refman_doc} -\chapter{After Block Example}\label{afterdoc_example}\hypertarget{afterdoc_example}{} -\subinputfrom{../html/examples/afterdoc/latex/}{refman_doc} -\chapter{QT Style Example}\label{qtstyle_example}\hypertarget{qtstyle_example}{} -\subinputfrom{../html/examples/qtstyle/latex/}{refman_doc} -\chapter{Javadoc Style Example}\label{jdstyle_example}\hypertarget{jdstyle_example}{} -\subinputfrom{../html/examples/jdstyle/latex/}{refman_doc} +\chapter{Style Examples} + \doxysection{After Block Example}\label{afterdoc_example}\hypertarget{afterdoc_example}{} + \begin{DoxygenSubAppendix} + \subinputfrom{../html/examples/afterdoc/latex/}{refman_doc} + \end{DoxygenSubAppendix} + \doxysection{QT Style Example}\label{qtstyle_example}\hypertarget{qtstyle_example}{} + \begin{DoxygenSubAppendix} + \subinputfrom{../html/examples/qtstyle/latex/}{refman_doc} + \end{DoxygenSubAppendix} + \doxysection{Javadoc Style Example}\label{jdstyle_example}\hypertarget{jdstyle_example}{} + \begin{DoxygenSubAppendix} + \subinputfrom{../html/examples/jdstyle/latex/}{refman_doc} + \end{DoxygenSubAppendix} + \doxysection{Javadoc Banner Example}\label{javadoc_banner_example}\hypertarget{javadoc_banner_example}{} + \begin{DoxygenSubAppendix} + \subinputfrom{../html/examples/javadoc-banner/latex/}{refman_doc} + \end{DoxygenSubAppendix} \chapter{Structural Commands Example}\label{structcmd_example}\hypertarget{structcmd_example}{} \subinputfrom{../html/examples/structcmd/latex/}{refman_doc} -\chapter{Python Docstring Example}\label{python_example}\hypertarget{python_example}{} -\subinputfrom{../html/examples/docstring/latex/}{refman_doc} -\chapter{Python Example}\label{py_example}\hypertarget{py_example}{} -\subinputfrom{../html/examples/pyexample/latex/}{refman_doc} -\chapter{VHDL Example}\label{vhdl_example}\hypertarget{vhdl_example}{} -\subinputfrom{../html/examples/mux/latex/}{refman_doc} -\chapter{Tcl Example}\label{tcl_example}\hypertarget{tcl_example}{} -\subinputfrom{../html/examples/tclexample/latex/}{refman_doc} +\chapter{Language Examples} + \doxysection{Python Docstring Example}\label{python_example}\hypertarget{python_example}{} + \begin{DoxygenSubAppendix} + \subinputfrom{../html/examples/docstring/latex/}{refman_doc} + \end{DoxygenSubAppendix} + \doxysection{Python Example}\label{py_example}\hypertarget{py_example}{} + \begin{DoxygenSubAppendix} + \subinputfrom{../html/examples/pyexample/latex/}{refman_doc} + \end{DoxygenSubAppendix} + \doxysection{VHDL Example}\label{vhdl_example}\hypertarget{vhdl_example}{} + \begin{DoxygenSubAppendix} + \subinputfrom{../html/examples/mux/latex/}{refman_doc} + \end{DoxygenSubAppendix} + \doxysection{Tcl Example}\label{tcl_example}\hypertarget{tcl_example}{} + \begin{DoxygenSubAppendix} + \subinputfrom{../html/examples/tclexample/latex/}{refman_doc} + \end{DoxygenSubAppendix} \chapter{Class Example}\label{class_example}\hypertarget{class_example}{} \subinputfrom{../html/examples/class/latex/}{refman_doc} 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 ); @@ -3553,6 +3553,24 @@ RAWEND ")"[^ \t\(\)\\]{0,16}\" BEGIN(SkipComment); } } +<*>^{B}*"/**"[*]+/[^/] { // special C "banner" comment block at a new line + if (Config_getBool(JAVADOC_BANNER) && Config_getBool(STRIP_CODE_COMMENTS)) + { + g_lastSpecialCContext = YY_START; + BEGIN(RemoveSpecialCComment); + } + else + { + // check is to prevent getting stuck in skipping C++ comments + if (YY_START != SkipCxxComment) + { + g_lastCContext = YY_START ; + } + startFontClass("comment"); + g_code->codify(yytext); + BEGIN(SkipComment); + } + } <*>^{B}*"/*"[!*]/[^/*] { // special C comment block at a new line if (Config_getBool(STRIP_CODE_COMMENTS)) { diff --git a/src/config.xml b/src/config.xml index 0b26571..0bf34a8 100644 --- a/src/config.xml +++ b/src/config.xml @@ -478,6 +478,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 5395e49..f94e4f8 100644 --- a/src/scanner.l +++ b/src/scanner.l @@ -6254,6 +6254,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; diff --git a/src/sqlcode.l b/src/sqlcode.l index c3dd679..d14bcfb 100644 --- a/src/sqlcode.l +++ b/src/sqlcode.l @@ -35,6 +35,7 @@ #include "config.h" #include "filedef.h" #include "tooltip.h" +#include "message.h" #define YY_NEVER_INTERACTIVE 1 #define YY_NO_INPUT 1 @@ -379,6 +380,7 @@ void parseSqlCode( sqlcodeYYlex_init_extra(&sqlcode_extra, &yyscanner); struct yyguts_t *yyg = (struct yyguts_t*)yyscanner; + printlex(yy_flex_debug, TRUE, __FILE__, fd ? fd->fileName().data(): NULL); yyextra->code = &od; yyextra->inputString = s; @@ -436,6 +438,7 @@ void parseSqlCode( sqlcodeYYlex_destroy(yyscanner); + printlex(yy_flex_debug, FALSE, __FILE__, fd ? fd->fileName().data(): NULL); return; } diff --git a/src/xmlcode.l b/src/xmlcode.l index e792ea9..42218b1 100644 --- a/src/xmlcode.l +++ b/src/xmlcode.l @@ -35,6 +35,7 @@ #include "config.h" #include "filedef.h" #include "tooltip.h" +#include "message.h" #define YY_NEVER_INTERACTIVE 1 #define YY_NO_INPUT 1 @@ -338,6 +339,7 @@ void parseXmlCode( ) { if (s.isEmpty()) return; + printlex(yy_flex_debug, TRUE, __FILE__, fd ? fd->fileName().data(): NULL); g_code = &od; g_inputString = s; @@ -393,6 +395,7 @@ void parseXmlCode( g_sourceFileDef=0; } + printlex(yy_flex_debug, FALSE, __FILE__, fd ? fd->fileName().data(): NULL); return; } |