Doxygen and plantuml

翻译 2012年03月27日 15:03:56
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).

捣鼓PlantUML(二、组件图)

简单介绍为什么先讲组件图,是因为我是由于需要画组件图所以才去找的这个工具。组件图实质就是将一个大系统,拆分为若干功能相对独立,互相之间存在关联依赖关系的组件集合。然后由一张图列出所有组件及它们之间的关...
  • zh_weir
  • zh_weir
  • 2016年11月03日 12:39
  • 1445

Eclipse下PlantUML 的安装及配置、Graphviz的安装和配置以及使用问题解决办法

注意:PlantUML一定要用到Graphviz。PlantUML使用Graphviz来生成相关图形(只有序列图可以不依赖它),其它图形都需要,因此得安装它,否则生成图形失败,且报错。 1.下载更新 ...
  • xing930408
  • xing930408
  • 2017年04月07日 14:38
  • 2073

Doxygen使用学习(六)------Doxygen的特殊命令字之"用于显示例子的命令"

用于显示例子(将被插入文档中的代码)的命令 @dontinclude 用于解析一个源文件,且不论是否被文档完整包含(如同@include命令所做的),如果你希望将源文件分割成最小的块,并在这些块中间...
  • qq_19528953
  • qq_19528953
  • 2016年08月21日 22:45
  • 663

PlantUML类图的写法

PlantUML类图 JavaChen Blog 2016-02-28 219 阅读 devops 类之间的关系 PlantUML用下面的符号来表示类之间的关系: 泛化, Generaliz...
  • changsimeng
  • changsimeng
  • 2017年01月13日 18:04
  • 2207

plantUML编辑器整理

如果你平常的编辑器就是 Intellij 系列软件,那么推荐直接使用Intellij 插件(最后一个) 在线编辑器:https://www.planttext.com/ 推荐这个 预...
  • lonewolf521125
  • lonewolf521125
  • 2017年06月07日 10:41
  • 610

绘图工具(代码实现绘图)---plantuml

基础入门第一个例子 时序图 流程图 源代码 图片展示 还有很多这里不再介绍最近看到asciidoc和plantuml;是编写文档的极好工具。相对word和visio,最大的好处是可以实现代码版本管理,...
  • u011729865
  • u011729865
  • 2016年10月29日 18:23
  • 2679

doxygen 使用简介(C,C++为代码作注释)

doxygen注释块 doxygen注释块其实就是在C"C++注释块的基础添加一些额外标识, 使doxygen把它识别出来, 并将它组织到生成的文档中去。 在每个代码项中都可以有两类描述,...
  • u012723995
  • u012723995
  • 2015年08月04日 16:13
  • 1165

使用 Sublime + PlantUML 高效地画图

http://www.jianshu.com/p/e92a52770832 http://plantuml.com/download.html http://www.sublimetext.com/...
  • zeng_84_long
  • zeng_84_long
  • 2016年08月15日 10:43
  • 1582

Doxygen使用学习(一)------Doxygen的简单注释格式

最近,我通过看别人的没有文档代码,终于醒悟了,感觉到了文档的重要性!(看不懂别人代码的痛苦太难受了!) 所以我觉定,趁着周末赶快学习一下如何使用文档生成工具。 通过网上检索,我发现Doxygen是一...
  • qq_19528953
  • qq_19528953
  • 2016年08月12日 12:52
  • 1180

ns3使用doxygen生成离线api文档

doxygen的维基介绍: Doxygen是一个编写软件参考文檔的工具。该文檔是直接写在源代码中,因此比较容易保持更新。Doxygen可以交叉引用文檔和源代码,使文件的读者可以很容易地引用实际的源代码...
  • zy416548283
  • zy416548283
  • 2014年08月05日 10:39
  • 3880
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:Doxygen and plantuml
举报原因:
原因补充:

(最多只允许输入30个字)