Bug 731947 - Support for PlantUML

doxygen · Aug 10, 2014 · 7506404 · 7506404
1 parent 97d12d0
commit 7506404
Show file tree

Hide file tree

Showing 31 changed files with 544 additions and 62 deletions.
diff --git a/Doxyfile b/Doxyfile
@@ -1,4 +1,4 @@
-# Doxyfile 1.8.3.1
+# Doxyfile 1.8.7
 
 #---------------------------------------------------------------------------
 # Project related configuration options
@@ -10,6 +10,7 @@ PROJECT_BRIEF          =
 PROJECT_LOGO           =
 OUTPUT_DIRECTORY       = doxygen_docs
 CREATE_SUBDIRS         = YES
+ALLOW_UNICODE_NAMES    = NO
 OUTPUT_LANGUAGE        = English
 BRIEF_MEMBER_DESC      = YES
 REPEAT_BRIEF           = YES
@@ -63,6 +64,7 @@ INTERNAL_DOCS          = NO
 CASE_SENSE_NAMES       = NO
 HIDE_SCOPE_NAMES       = NO
 SHOW_INCLUDE_FILES     = YES
+SHOW_GROUPED_MEMB_INC  = NO
 FORCE_LOCAL_INCLUDES   = NO
 INLINE_INFO            = YES
 SORT_MEMBER_DOCS       = YES
@@ -84,7 +86,7 @@ FILE_VERSION_FILTER    =
 LAYOUT_FILE            =
 CITE_BIB_FILES         =
 #---------------------------------------------------------------------------
-# configuration options related to warning and progress messages
+# Configuration options related to warning and progress messages
 #---------------------------------------------------------------------------
 QUIET                  = NO
 WARNINGS               = YES
@@ -94,9 +96,10 @@ WARN_NO_PARAMDOC       = NO
 WARN_FORMAT            = "$file:$line: $text "
 WARN_LOGFILE           =
 #---------------------------------------------------------------------------
-# configuration options related to the input files
+# Configuration options related to the input files
 #---------------------------------------------------------------------------
-INPUT                  = src
+INPUT                  = src \
+                         vhdlparser
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          = *.h \
                          *.cpp \
@@ -105,6 +108,7 @@ RECURSIVE              = NO
 EXCLUDE                = src/logos.cpp \
                          src/lodepng.cpp
 EXCLUDE_SYMLINKS       = NO
+EXCLUDE_PATTERNS       =
 EXCLUDE_SYMBOLS        =
 EXAMPLE_PATH           =
 EXAMPLE_PATTERNS       =
@@ -116,26 +120,25 @@ FILTER_SOURCE_FILES    = NO
 FILTER_SOURCE_PATTERNS =
 USE_MDFILE_AS_MAINPAGE =
 #---------------------------------------------------------------------------
-# configuration options related to source browsing
+# Configuration options related to source browsing
 #---------------------------------------------------------------------------
 SOURCE_BROWSER         = YES
 INLINE_SOURCES         = NO
 STRIP_CODE_COMMENTS    = YES
 REFERENCED_BY_RELATION = YES
 REFERENCES_RELATION    = YES
 REFERENCES_LINK_SOURCE = YES
+SOURCE_TOOLTIPS        = YES
 USE_HTAGS              = NO
 VERBATIM_HEADERS       = YES
-CLANG_ASSISTED_PARSING = YES
-CLANG_OPTIONS          =
 #---------------------------------------------------------------------------
-# configuration options related to the alphabetical class index
+# Configuration options related to the alphabetical class index
 #---------------------------------------------------------------------------
 ALPHABETICAL_INDEX     = YES
 COLS_IN_ALPHA_INDEX    = 5
 IGNORE_PREFIX          =
 #---------------------------------------------------------------------------
-# configuration options related to the HTML output
+# Configuration options related to the HTML output
 #---------------------------------------------------------------------------
 GENERATE_HTML          = YES
 HTML_OUTPUT            =
@@ -184,6 +187,7 @@ USE_MATHJAX            = NO
 MATHJAX_FORMAT         = HTML-CSS
 MATHJAX_RELPATH        = http://cdn.mathjax.org/mathjax/latest
 MATHJAX_EXTENSIONS     =
+MATHJAX_CODEFILE       =
 SEARCHENGINE           = YES
 SERVER_BASED_SEARCH    = YES
 EXTERNAL_SEARCH        = NO
@@ -192,7 +196,7 @@ SEARCHDATA_FILE        = searchdata.xml
 EXTERNAL_SEARCH_ID     =
 EXTRA_SEARCH_MAPPINGS  =
 #---------------------------------------------------------------------------
-# configuration options related to the LaTeX output
+# Configuration options related to the LaTeX output
 #---------------------------------------------------------------------------
 GENERATE_LATEX         = NO
 LATEX_OUTPUT           =
@@ -211,7 +215,7 @@ LATEX_HIDE_INDICES     = NO
 LATEX_SOURCE_CODE      = NO
 LATEX_BIB_STYLE        = plain
 #---------------------------------------------------------------------------
-# configuration options related to the RTF output
+# Configuration options related to the RTF output
 #---------------------------------------------------------------------------
 GENERATE_RTF           = NO
 RTF_OUTPUT             =
@@ -220,31 +224,31 @@ RTF_HYPERLINKS         = NO
 RTF_STYLESHEET_FILE    =
 RTF_EXTENSIONS_FILE    =
 #---------------------------------------------------------------------------
-# configuration options related to the man page output
+# Configuration options related to the man page output
 #---------------------------------------------------------------------------
 GENERATE_MAN           = NO
 MAN_OUTPUT             =
 MAN_EXTENSION          = .3
+MAN_SUBDIR             =
 MAN_LINKS              = NO
 #---------------------------------------------------------------------------
-# configuration options related to the XML output
+# Configuration options related to the XML output
 #---------------------------------------------------------------------------
 GENERATE_XML           = NO
 XML_OUTPUT             = xml
-XML_SCHEMA             =
-XML_DTD                =
 XML_PROGRAMLISTING     = YES
 #---------------------------------------------------------------------------
-# configuration options related to the DOCBOOK output
+# Configuration options related to the DOCBOOK output
 #---------------------------------------------------------------------------
 GENERATE_DOCBOOK       = NO
 DOCBOOK_OUTPUT         = docbook
+DOCBOOK_PROGRAMLISTING = NO
 #---------------------------------------------------------------------------
-# configuration options for the AutoGen Definitions output
+# Configuration options for the AutoGen Definitions output
 #---------------------------------------------------------------------------
 GENERATE_AUTOGEN_DEF   = NO
 #---------------------------------------------------------------------------
-# configuration options related to the Perl module output
+# Configuration options related to the Perl module output
 #---------------------------------------------------------------------------
 GENERATE_PERLMOD       = NO
 PERLMOD_LATEX          = NO
@@ -257,13 +261,14 @@ ENABLE_PREPROCESSING   = YES
 MACRO_EXPANSION        = YES
 EXPAND_ONLY_PREDEF     = YES
 SEARCH_INCLUDES        = YES
-INCLUDE_PATH           = qtools libmd5
+INCLUDE_PATH           = qtools \
+                         libmd5
 INCLUDE_FILE_PATTERNS  =
 PREDEFINED             =
 EXPAND_AS_DEFINED      =
 SKIP_FUNCTION_MACROS   = YES
 #---------------------------------------------------------------------------
-# Configuration::additions related to external references
+# Configuration options related to external references
 #---------------------------------------------------------------------------
 TAGFILES               = qtools_docs/qtools.tag=../../qtools_docs/html
 GENERATE_TAGFILE       = doxygen.tag
@@ -276,6 +281,7 @@ PERL_PATH              = /usr/bin/perl
 #---------------------------------------------------------------------------
 CLASS_DIAGRAMS         = NO
 MSCGEN_PATH            =
+DIA_PATH               =
 HIDE_UNDOC_RELATIONS   = YES
 HAVE_DOT               = YES
 DOT_NUM_THREADS        = 0
@@ -299,6 +305,8 @@ INTERACTIVE_SVG        = YES
 DOT_PATH               =
 DOTFILE_DIRS           =
 MSCFILE_DIRS           =
+DIAFILE_DIRS           =
+PLANTUML_JAR_PATH      =
 DOT_GRAPH_MAX_NODES    = 50
 MAX_DOT_GRAPH_DEPTH    = 0
 DOT_TRANSPARENT        = NO

diff --git a/doc/commands.doc b/doc/commands.doc
@@ -90,6 +90,7 @@ documentation:
 \refitem cmdendrtfonly \\endrtfonly
 \refitem cmdendsecreflist \\endsecreflist
 \refitem cmdendverbatim \\endverbatim
+\refitem cmdenduml \\enduml
 \refitem cmdendxmlonly \\endxmlonly
 \refitem cmdenum \\enum
 \refitem cmdexample \\example
@@ -174,6 +175,7 @@ documentation:
 \refitem cmdskip \\skip
 \refitem cmdskipline \\skipline
 \refitem cmdsnippet \\snippet
+\refitem cmdstartuml \\startuml
 \refitem cmdstruct \\struct
 \refitem cmdsubpage \\subpage
 \refitem cmdsubsection \\subsection
@@ -2530,6 +2532,59 @@ class Receiver
 
   \sa section \ref cmdmscfile "\\mscfile".
 
+<hr>
+\section cmdstartuml \\startuml
+
+  \addindex \\startuml
+  Starts a text fragment which should contain a valid description of a
+  PlantUML diagram. See http://plantuml.sourceforge.net/ for examples.
+  The text fragment ends with \ref cmdenduml "\\enduml".
+  \note You need to install Java and the PlantUML's jar file,
+  if you want to use this command. The location of the jar file should be specified
+  using \ref cfg_plantuml_jar_path "PLANTUML_JAR_PATH".
+
+Here is an example of the use of the \c \\startuml command.
+\code
+/** Sender class. Can be used to send a command to the server.
+ *  The receiver will acknowledge the command by calling Ack().
+ *  \startuml
+ *    Sender->Receiver  : Command()
+ *    Sender<--Receiver : Ack()
+ *  \enduml
+ */
+class Sender
+{
+  public:
+    /** Acknowledgment from server */
+    void Ack(bool ok);
+};
+
+/** Receiver class. Can be used to receive and execute commands.
+ *  After execution of a command, the receiver will send an acknowledgment
+ *  \startuml
+ *    Receiver<-Sender  : Command()
+ *    Receiver-->Sender : Ack()
+ *  \enduml
+ */
+class Receiver
+{
+  public:
+    /** Executable a command on the server */
+    void Command(int commandId);
+};
+\endcode
+
+\note For compatibility with running PlantUML as a preprocessing step before
+running doxygen, you can also add the name of the image file after \c \\startuml
+and inside curly brackets, i.e.
+\verbatim
+@startuml{myimage.png}
+Alice -> Bob : Hello
+@enduml
+\endverbatim
+When the name of the image is specified, doxygen will generate an image with that name.
+Without the name doxygen will choose a name automatically.
+
 <hr>
 \section cmddotfile \\dotfile <file> ["caption"]
 
@@ -2650,6 +2705,12 @@ class Receiver
   \addindex \\endmsc
   Ends a block that was started with \ref cmdmsc "\\msc".
 
+<hr>
+\section cmdenduml \\enduml
+
+  \addindex \\enduml
+  Ends a block that was started with \ref cmdstartuml "\\startuml".
+
 <hr>
 \section cmdendhtmlonly \\endhtmlonly
 

diff --git a/src/cmdmapper.cpp b/src/cmdmapper.cpp
@@ -120,8 +120,10 @@ CommandMap cmdMap[] =
   { "_internalref",  CMD_INTERNALREF },
   { "dot",           CMD_DOT },
   { "msc",           CMD_MSC },
+  { "startuml",      CMD_STARTUML },
   { "enddot",        CMD_ENDDOT },
   { "endmsc",        CMD_ENDMSC },
+  { "enduml",        CMD_ENDUML },
   { "manonly",       CMD_MANONLY },
   { "endmanonly",    CMD_ENDMANONLY },
   { "includelineno", CMD_INCWITHLINES },

diff --git a/src/cmdmapper.h b/src/cmdmapper.h
@@ -127,7 +127,9 @@ enum CommandType
   CMD_DIAFILE      = 97,
   CMD_LATEXINCLUDE = 98,
   CMD_NDASH        = 99,
-  CMD_MDASH        = 100
+  CMD_MDASH        = 100,
+  CMD_STARTUML     = 101,
+  CMD_ENDUML       = 102
 };
 
 enum HtmlTagType

diff --git a/src/commentcnv.l b/src/commentcnv.l
@@ -446,7 +446,7 @@ void replaceComment(int offset);
 				     g_blockName=&yytext[1];
                                      BEGIN(VerbatimCode);
   				   }
-<CComment,ReadLine>[\\@]("dot"|"code"|"msc")/[^a-z_A-Z0-9] { /* start of a verbatim block */
+<CComment,ReadLine>[\\@]("dot"|"code"|"msc"|"startuml")/[^a-z_A-Z0-9] { /* start of a verbatim block */
                                      copyToOutput(yytext,(int)yyleng); 
 				     g_lastCommentContext = YY_START;
 				     g_javaBlock=0;
@@ -517,7 +517,7 @@ void replaceComment(int offset);
 				       }
 				     }
   				   }
-<VerbatimCode>[\\@]("enddot"|"endcode"|"endmsc") { /* end of verbatim block */
+<VerbatimCode>[\\@]("enddot"|"endcode"|"endmsc"|"enduml") { /* end of verbatim block */
                                      copyToOutput(yytext,(int)yyleng);
 				     if (&yytext[4]==g_blockName)
 				     {
@@ -554,7 +554,7 @@ void replaceComment(int offset);
                                      copyToOutput(yytext,(int)yyleng); 
                                    }
 <Verbatim>^[ \t]*"///"             {
-  				     if (g_blockName=="dot" || g_blockName=="msc" || g_blockName.at(0)=='f')
+  				     if (g_blockName=="dot" || g_blockName=="msc" || g_blockName=="startuml" || g_blockName.at(0)=='f')
 				     {
 				       // see bug 487871, strip /// from dot images and formulas.
                                        int l=0;

diff --git a/src/commentscan.l b/src/commentscan.l
@@ -191,6 +191,7 @@ static DocCmdMap docCmdMap[] =
   { "manonly",         &handleFormatBlock,      FALSE },
   { "dot",             &handleFormatBlock,      TRUE  },
   { "msc",             &handleFormatBlock,      TRUE  },
+  { "startuml",        &handleFormatBlock,      TRUE  },
   { "code",            &handleFormatBlock,      TRUE  },
   { "addindex",        &handleAddIndex,         FALSE },
   { "if",              &handleIf,               FALSE },
@@ -877,7 +878,7 @@ static int yyread(char *buf,int max_size)
        /* start command character */
 CMD	  ("\\"|"@")
 DCMD1     ("arg"|"attention"|"author"|"cite"|"code")
-DCMD2     ("date"|"dot"|"msc"|"dotfile"|"example")
+DCMD2     ("date"|"dot"|"msc"|"dotfile"|"example"|"startuml")
 DCMD3     ("htmlinclude"|"htmlonly"|"image"|"include")
 DCMD4     ("includelineno"|"internal"|"invariant")
 DCMD5     ("latexinclude"|"latexonly"|"li"|"line"|"manonly"|"name")
@@ -1785,6 +1786,13 @@ RCSTAG    "$"{ID}":"[^\n$]+"$"
   					    BEGIN(Comment);
 					  }
   					}
+<FormatBlock>{CMD}"enduml"              {
+  					  addOutput(yytext);
+					  if (blockName=="startuml") // found end of the block
+					  {
+  					    BEGIN(Comment);
+					  }
+                                        }
 <FormatBlock>[^ \@\*\/\\\n]*		{ // some word
   					  addOutput(yytext);
   					}
@@ -1809,9 +1817,11 @@ RCSTAG    "$"{ID}":"[^\n$]+"$"
   					  addOutput(*yytext);
   					}
 <FormatBlock><<EOF>>			{
+                                          QCString endTag = "@end"+blockName;
+                                          if (blockName=="startuml") endTag="enduml";
                                           warn(yyFileName,yyLineNr,
-	                                    "reached end of comment while inside a @%s block; check for missing @end%s tag!",
-	                                    blockName.data(),blockName.data()
+	                                    "reached end of comment while inside a @%s block; check for missing @%s tag!",
+	                                    blockName.data(),endTag.data()
 	                                  );				
 					  yyterminate();
     					}

diff --git a/src/compound.xsd b/src/compound.xsd
@@ -386,7 +386,7 @@
       <xsd:element name="rtfonly" type="xsd:string" />
       <xsd:element name="latexonly" type="xsd:string" />
       <xsd:element name="dot" type="xsd:string" />
-      <xsd:element name="msc" type="xsd:string" />
+      <xsd:element name="plantuml" type="xsd:string" />
       <xsd:element name="anchor" type="docAnchorType" />
       <xsd:element name="formula" type="docFormulaType" />
       <xsd:element name="ref" type="docRefTextType" />