Doxygen and plantuml

Doxygen
You can use Doxygen and PlantUML together to integrate UML diagrams into generated documentation :

Defining aliases
Doxygen does not understand the @startuml and @enduml tags, and will generate errors if you use them in comments. You can surround them by HTML comments to have Doxygen ignore them (see below for an example). However, you can also define Doxygen aliases in your Doxyfile for @startuml and @enduml, so that HTML comments are not necessary:

ALIASES = "startuml=\if DontIgnorePlantUMLCode"
ALIASES += "enduml=\endif"

This will have Doxygen ignore everything in-between @startuml and @enduml unless the token 'DontIgnorePlantUMLCode' is defined, which of course isn't.

You can even go one step further: Doxygen supports arguments in aliases, with the syntax @startuml{some argument}. This means you can generate the \image commands automatically:

ALIASES = "startuml{1}=\image html \1\n\image latex \1\n\if DontIgnorePlantUMLCode"
ALIASES += "enduml=\endif"

Now, you can just do:

@startuml{myfilename.png}
.. PlantUML code
@enduml

Starting with version 7560, PlantUML will recognize @startuml{myfilename.png} as @startuml myfilename.png or @startuml "myfilename.png"
Batch example (for Windows)

The following batch file is called for each source directory :

...
:: parameter %1 is the source directory
:: parameter %2 is the image output directory

:: set tools
SET GRAPHVIZ_DOT=d:\Programme\Dev\graphviz\bin\dot.exe
SET DOXYGEN_EXE=d:\Programme\Dev\doxygen\doxygen.exe
SET PLANTUML_JAR=d:\Programme\Dev\plantuml\plantuml.jar

:: set source dir
SET SOURCE_DIR=%1

:: set image output folder for plantuml / image source folder for doxygen
SET DOC_IMG_PATH=%2

:: change to source dir and save old dir on stack
PUSHD "%SOURCE_DIR%"

:: call plantuml.jar for current dir
java -jar %PLANTUML_JAR% -v -o "%DOC_IMG_PATH%" "./**.(c|cpp|doc|h)"

:: call doxygen for current dir (doxyfile)
%DOXYGEN_EXE% doxyfile

:: change to saved dir
POPD
...


Additionally inside doxyfile the configuration value for image folder (for @image command) is assigned:

...
IMAGE_PATH = $(DOC_IMG_PATH)
...


Batch example (for Linux)

#!/bin/sh
# Create *.png files from text @startuml code and output *.png images to ./doc-src/images folder
# Recusively search from current folder scanning *.c, *.cpp, *.h, and *.doc files
java  -Djava.awt.headless=true -jar $PLANTUML_JAR -v -o $PWD/doc-src/images  "./**.(c|cpp|doc|h)"
doxygen

C Source example (Using alias)
Here is an example how the comment is used for plantuml and doxygen in C source file:

...
/*!
* @brief This function sends compute requests to
* ZipComp-Task and waits for response:
*
* @startuml{ZipCmd_ZipComp_Communication.png}
*
* ZipCmd -> ZipComp: First Compute Request
* ZipCmd <-- ZipComp: First Compute Response
*
* ZipCmd -> ZipComp: Second Compute Request
* ZipCmd <-- ZipComp: Second Compute Response
*
* @enduml
*
* @return some value on success.
*/
unsigned int ZipCmd_ZipComp_Communication(unsigned short command, unsigned
char *buffer);
...


C Source example (Old version)
Here is an example how the comment is used for plantuml and doxygen in C source file:

...
/*!
* @brief This function sends compute requests to
* ZipComp-Task and waits for response:
* @image html ZipCmd_ZipComp_Communication.png
*
* <!-- Hide plantuml commands from Doxygen inside comment.
*  Note: Use of the Doxygen tag command to hide code in 1.7.3 will hide the Doxygen docs that follow.
*  Warning: Don't replaced plantuml commands '@' with '\' - it won't work.
* @startuml ZipCmd_ZipComp_Communication.png
*
* ZipCmd -> ZipComp: First Compute Request
* ZipCmd <-- ZipComp: First Compute Response
*
* ZipCmd -> ZipComp: Second Compute Request
* ZipCmd <-- ZipComp: Second Compute Response
*
* @enduml
* -->
*
* @return some value on success.
*/
unsigned int ZipCmd_ZipComp_Communication(unsigned short command, unsigned
char *buffer);
...


@image is used in doxygen to include an image in documentation. The image file name must be the same is used after @startuml command (here: ZipCmd_ZipComp_Communication.png).