doxygen
===
###### tags: `doxygen` `markdown`
# install
prerequest
```
GNU tools,flex,bison,libconv,GNU make strip
cmake
```
get source and install
```
git clone https://github.com/doxygen/doxygen.git
cd doxygen
mkdir build
cd build
cmake -G "Unix Makefiles" ..
# cmake -Dbuild_wizard=YES .. # build qt GUI front end
# cmake -L # overview the configuration
make # make install
# optional
cmake -Dbuild_doc=YES
make docs
```
# Getting start
1. 確定Doxygen支援的語言, 包括C, C++, C#, Objective-C, IDL, Java, VHDL, PHP, Python, Tcl, Fortran, and D. 但doxygen
提供客製化的設定，可以參考[這裡](http://www.stack.nl/~dimitri/doxygen/manual/config.html#cfg_extension_mapping)
2. Creating a configuration file
doxygen 在使用之前必須加入設定檔
```
doxygen -g <config-file>
```
3. Running doxygen
doxygen 會根據config-file 的內容選擇輸出的格式和目的地
支援的格式有HTML, RTF, $\mbox{\LaTeX}$, XML, Unix-Man page, DocBook
預設輸出是在doxygen 的config-file的位置
```
doxygen <config-file>
```
# doxygen doc
http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html
# javadoc
<table class="wikitable">
<tbody><tr>
<th>Tag & Parameter</th>
<th>Usage</th>
<th>Applies to</th>
<th>Since</th>
</tr>
<tr>
<td><b>@author</b> <i>John Smith</i></td>
<td>Describes an author.</td>
<td>Class, Interface, Enum</td>
<td></td>
</tr>
<tr>
<td><b>@version</b> <i>version</i></td>
<td>Provides software version entry. Max one per Class or Interface.</td>
<td>Class, Interface, Enum</td>
<td></td>
</tr>
<tr>
<td><b>@since</b> <i>since-text</i></td>
<td>Describes when this functionality has first existed.</td>
<td>Class, Interface, Enum, Field, Method</td>
<td></td>
</tr>
<tr>
<td><b>@see</b> <i>reference</i></td>
<td>Provides a link to other element of documentation.</td>
<td>Class, Interface, Enum, Field, Method</td>
<td></td>
</tr>
<tr>
<td><b>@param</b> <i>name description</i></td>
<td>Describes a method parameter.</td>
<td>Method</td>
<td></td>
</tr>
<tr>
<td><b>@return</b> <i>description</i></td>
<td>Describes the return value.</td>
<td>Method</td>
<td></td>
</tr>
<tr>
<td><b>@exception</b> <i>classname description</i><br>
<b>@throws</b> <i>classname description</i></td>
<td>Describes an exception that may be thrown from this method.</td>
<td>Method</td>
<td></td>
</tr>
<tr>
<td><b>@deprecated</b> <i>description</i></td>
<td>Describes an outdated method.</td>
<td>Class, Interface, Enum, Field, Method</td>
<td></td>
</tr>
<tr>
<td>{<b>@inheritDoc</b>}</td>
<td>Copies the description from the overridden method.</td>
<td>Overriding Method</td>
<td>1.4.0</td>
</tr>
<tr>
<td>{<b>@link</b> <i>reference</i>}</td>
<td>Link to other symbol.</td>
<td>Class, Interface, Enum, Field, Method</td>
<td></td>
</tr>
<tr>
<td>{<b>@value</b> <i>#STATIC_FIELD</i>}</td>
<td>Return the value of a static field.</td>
<td>Static Field</td>
<td>1.4.0</td>
</tr>
<tr>
<td>{<b>@code</b> <i>literal</i>}</td>
<td>Formats literal text in the code font. It is equivalent to <code>{@literal}</code>.</td>
<td>Class, Interface, Enum, Field, Method</td>
<td>1.5.0</td>
</tr>
<tr>
<td>{<b>@literal</b> <i>literal</i>}</td>
<td>Denotes literal text. The enclosed text is interpreted as not containing HTML markup or nested javadoc tags.</td>
<td>Class, Interface, Enum, Field, Method</td>
<td>1.5.0</td>
</tr>
</tbody></table>
## link usage example
```java=
public class SampleLink{
String variable;
/**
* Sets variable
* Refer {@link SampleLink#getVar() getName} to get variable.
* @param var variable
*/
public void setVar(String var){
variable = var;
}
/**
* Gets variable.
* Refer {@link #setVar(String)} for setting variable.
* @return variable String
*/
public String getVar(){
return variable;
}
}
```
## cmment block for c-like language(c,c++,java...)
### block:
JavaDoc style:
```
/**
* ... text ...
*/
```
Qt style:
```
/*!
* ... text ...
*/
```
more visible
```
/********************//**
* ... text ...
************************/
```
### brief description:
若使用Java style 的brief 時，必須要將JAVADOC_AUTOBRIEF 設成YES
```
/** Brief description which ends at this dot. Details follow
* here.
*/
```
### Putting documentation after members
通常放至於file,struct,class,enum,union之後 用來解釋變數,需要加入<符號
```
int var; /*!< Detailed description after the member */
```
```
int var; /**< Detailed description after the member */
```
piece of example:
param:parameter
return:return description
sa:see also
```clike=
//! A test class.
/*!
A more elaborate class description.
*/
class QTstyle_Test
{
public:
//! An enum.
/*! More detailed enum description. */
enum TEnum {
TVal1, /*!< Enum value TVal1. */
TVal2, /*!< Enum value TVal2. */
TVal3 /*!< Enum value TVal3. */
}
//! Enum pointer.
/*! Details. */
*enumPtr,
//! Enum variable.
/*! Details. */
enumVar;
//! A constructor.
/*!
A more elaborate description of the constructor.
*/
QTstyle_Test();
//! A destructor.
/*!
A more elaborate description of the destructor.
*/
~QTstyle_Test();
//! A normal member taking two arguments and returning an integer value.
/*!
\param a an integer argument.
\param s a constant character pointer.
\return The test results
\sa QTstyle_Test(), ~QTstyle_Test(), testMeToo() and publicVar()
*/
int testMe(int a,const char *s);
//! A pure virtual member.
/*!
\sa testMe()
\param c1 the first argument.
\param c2 the second argument.
*/
virtual void testMeToo(char c1,char c2) = 0;
//! A public variable.
/*!
Details.
*/
int publicVar;
//! A function variable.
/*!
Details.
*/
int (*handler)(int a,int b);
};
```
click [here](http://www.stack.nl/~dimitri/doxygen/manual/examples/qtstyle/html/class_test.html) for generate example
JavaDoc style
要將JAVADOC_AUTOBRIEF 設成YES
```clike=
/**
* A test class. A more elaborate class description.
*/
class Javadoc_Test
{
public:
/**
* An enum.
* More detailed enum description.
*/
enum TEnum {
TVal1, /**< enum value TVal1. */
TVal2, /**< enum value TVal2. */
TVal3 /**< enum value TVal3. */
}
*enumPtr, /**< enum pointer. Details. */
enumVar; /**< enum variable. Details. */
/**
* A constructor.
* A more elaborate description of the constructor.
*/
Javadoc_Test();
/**
* A destructor.
* A more elaborate description of the destructor.
*/
~Javadoc_Test();
/**
* a normal member taking two arguments and returning an integer value.
* @param a an integer argument.
* @param s a constant character pointer.
* @see Javadoc_Test()
* @see ~Javadoc_Test()
* @see testMeToo()
* @see publicVar()
* @return The test results
*/
int testMe(int a,const char *s);
/**
* A pure virtual member.
* @see testMe()
* @param c1 the first argument.
* @param c2 the second argument.
*/
virtual void testMeToo(char c1,char c2) = 0;
/**
* a public variable.
* Details.
*/
int publicVar;
/**
* a function variable.
* Details.
*/
int (*handler)(int a,int b);
};
```
### Documentation at other places
doxygen 允許使用者在任意位置生成說明
差別是c++ style使用backslash來作為command的前綴，而java style利用@作為前綴 從上面兩個piece of code可以看出來
structural commands:
```
\struct to document a C-struct.
\union to document a union.
\enum to document an enumeration type.
\fn to document a function.
\var to document a variable or typedef or enum value.
\def to document a #define.
\typedef to document a type definition.
\file to document a file.
\namespace to document a namespace.
\package to document a Java package.
\interface to document an IDL interface.
```
example:
```clike=
/*! \file structcmd.h
\brief A Documented file.
Details.
*/
/*! \def MAX(a,b)
\brief A macro that returns the maximum of \a a and \a b.
Details.
*/
/*! \var typedef unsigned int UINT32
\brief A type definition for a .
Details.
*/
/*! \var int errno
\brief Contains the last error code.
\warning Not thread safe!
*/
/*! \fn int open(const char *pathname,int flags)
\brief Opens a file descriptor.
\param pathname The name of the descriptor.
\param flags Opening flags.
*/
/*! \fn int close(int fd)
\brief Closes the file descriptor \a fd.
\param fd The descriptor to close.
*/
/*! \fn size_t write(int fd,const char *buf, size_t count)
\brief Writes \a count bytes from \a buf to the filedescriptor \a fd.
\param fd The descriptor to write to.
\param buf The data buffer to write.
\param count The number of bytes to write.
*/
/*! \fn int read(int fd,char *buf,size_t count)
\brief Read bytes from a file descriptor.
\param fd The descriptor to read from.
\param buf The buffer to read into.
\param count The number of bytes to read.
*/
#define MAX(a,b) (((a)>(b))?(a):(b))
typedef unsigned int UINT32;
int errno;
int open(const char *,int);
int close(int);
size_t write(int,const char *, size_t);
int read(int,char *,size_t);
```
[所有的special commands](http://www.stack.nl/~dimitri/doxygen/manual/commands.html)
:::info
to document global objects (functions, typedefs, enum, macros, etc), you must document the file in which they are defined. In other words, there must at least be a
```
/*! \file */
```
or a
```
/** @file */
```
line in this file.
:::
:::info
If you have a file that doxygen cannot parse but still would like to document it, you can show it as-is using \verbinclude, e.g.
/*! \file myscript.sh
\* Look at this nice script:
\* \verbinclude myscript.sh
\*/
Make sure that the script is explicitly listed in the INPUT or that FILE_PATTERNS includes the .sh extension and the the script can be found in the path set via EXAMPLE_PATH.
:::
# Comment blocks in Python
```python=
"""@package docstring
Documentation for this module.
More details.
"""
def func():
"""Documentation for a function.
More details.
"""
pass
class PyClass:
"""Documentation for a class.
More details.
"""
def __init__(self):
"""The constructor."""
self._memVar = 0;
def PyMethod(self):
"""Documentation for a method."""
pass
```
這種形式的不能使用doxygen特殊command
Here is the same example again but now using doxygen style comments:
```python=
## @package pyexample
# Documentation for this module.
#
# More details.
## Documentation for a function.
#
# More details.
def func():
pass
## Documentation for a class.
#
# More details.
class PyClass:
## The constructor.
def __init__(self):
self._memVar = 0;
## Documentation for a method.
# @param self The object pointer.
def PyMethod(self):
pass
## A class variable.
classVar = 0;
## @var _memVar
# a member variable
```
若使用doxygen形式則要把 OPTIMIZE_OUTPUT_JAVA設為YES
# Markdown support
doxygen 支援Markdown語法 Markdown的教學請看
[這裡](http://markdown.tw/)
[markdown cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
## Emphasis
To emphasize a text fragment you start and end the fragment with an underscore or star. Using two stars or underscores will produce strong emphasis.
Examples:
```
single asterisks*
_single underscores_
double asterisks**
__double underscores__
```
## Links
doxygen support 2 links define by markdown:`inline` and `reference`
Inline Links
```
[The link text](http://example.net/)
[The link text](http://example.net/ "Link title")
[The link text](/relative/path/to/index.html "Link title")
[The link text](somefile.html)
```
In addition doxygen provides a similar way to link a documented entity:
```
[The link text](@ref MyClass)
```
Reference Links
Instead of putting the URL inline, you can also define the link separately and then refer to it from within the text.
The link definition looks as follows:
```
[link name]: http://www.example.com "Optional title"
```
can be used to refer to the link. Note that the link name matching is not case sensitive as is shown in the following example:
```
I get 10 times more traffic from [Google] than from
[Yahoo] or [MSN].
[google]: http://google.com/ "Google"
[yahoo]: http://search.yahoo.com/ "Yahoo Search"
[msn]: http://search.msn.com/ "MSN Search"
```
Link definitions will not be visible in the output.
Like for inline links doxygen also supports @ref inside a link definition:
```
[myclass]: @ref MyClass "My class"
```
## Images
Markdown syntax for images is similar to that for links. The only difference is an additional ! before the link text.
Examples:
```
![Caption text][img def]
![img def]
[img def]: /path/to/img.jpg "Optional Title"
```
Also here you can use @ref to link to an image:
```
![img def]
[img def]: @ref image.png "Caption text"
```
The caption text is optional.
## Automatic Linking
To create a link to an URL or e-mail address Markdown supports the following syntax:
```
<http://www.example.com>
<https://www.example.com>
<ftp://www.example.com>
<mailto:address@example.com>
<address@example.com>
```
:::info
Note that doxygen will also produce the links without the angle brackets.
:::
## Header Id Attributes
Standard Markdown has no support for labeling headers, which is a problem if you want to link to a section.
PHP Markdown Extra allows you to label a header by adding the following to the header
```
Header 1 {#labelid}
========
## Header 2 ## {#labelid2}
```
To link to a section in the same comment block you can use
```
[Link text](#labelid)
```
to link to a section in general, doxygen allows you to use @ref
```
[Link text](@ref labelid)
```
:::info
Note this only works for the headers of level 1 to 4.
:::
## Doxygen specifics
### Including Markdown files as pages
Doxygen會將資料夾下的.md或是.markdown轉成page。
預設的名稱和標題會採用該.md檔案的檔名,如果有設定level1 header doxygen 會將title設定成該header的名稱，如果有設定Header Id attribute ,doxygen會將page名稱設定為該名稱。
Here is an example of a file `README.md` that will appear as the main page when processed by doxygen:
```
My Main Page {#mainpage}
============
Documentation that will appear on the main page
```
If a page has a label you can link to it using `@ref` as is shown above. To refer to a markdown page without such label you can simple use the file name of the page, e.g.
```
See [the other page](other.md) for more info.
```
## Debugging of problems
```
doxygen -d
```
# Lists
Doxygen provides a number of ways to create lists of items.
Using dashes
By putting a number of column-aligned minus (-) signs at the start of a line, a bullet list will automatically be generated. Instead of the minus sign also plus (+) or asterisk (*) can be used.
Numbered lists can also be generated by using a minus followed by a hash or by using a number followed by a dot.
Nesting of lists is allowed and is based on indentation of the items.
Here is an example:
```
/*!
* A list of events:
* - mouse events
* -# mouse move event
* -# mouse click event\n
* More info about the click event.
* -# mouse double click event
* - keyboard events
* 1. key down event
* 2. key up event
*
* More text here.
*/
```
The result will be:
If you use tabs for indentation within lists, please make sure that `TAB_SIZE` in the configuration file is set to the correct tab size.
You can end a list by starting a new paragraph or by putting a dot (.) on an empty line at the same indentation level as the list you would like to end.
Here is an example that speaks for itself:
```
/**
* Text before the list
* - list item 1
* - sub item 1
* - sub sub item 1
* - sub sub item 2
* .
* The dot above ends the sub sub item list.
*
* More text for the first sub item
* .
* The dot above ends the first sub item.
*
* More text for the first list item
* - sub item 2
* - sub item 3
* - list item 2
* .
* More text in the same paragraph.
*
* More text in a new paragraph.
*/
```
Using HTML commands
If you like you can also use HTML commands inside the documentation blocks.
Here is the above example with HTML commands:
```
/*!
* A list of events:
* <ul>
* <li> mouse events
* <ol>
* <li>mouse move event
* <li>mouse click event<br>
* More info about the click event.
* <li>mouse double click event
* </ol>
* <li> keyboard events
* <ol>
* <li>key down event
* <li>key up event
* </ol>
* </ul>
* More text here.
*/
```
:::info
In this case the indentation is not important.
:::
# Grouping
## Modules
```
/defgroup \[group identity\] \[group name\]
\[description\]
```
define 一個group
```
/** \addtogroup <label>
* @{
*/
...
/** @}*/
```
To avoid putting `\ingroup` commands in the documentation for each member you can also group members together by the open marker `@{ `before the group and the closing marker `@} `after the group. The markers can be put in the documentation of the group definition or in a separate documentation block.
Groups themselves can also be nested using these grouping markers.
You will get an error message when you use the same group label more than once. If you don't want doxygen to enforce unique labels, then you can use `\addtogroup` instead of `\defgroup`. It can be used exactly like `\defgroup`, but when the group has been defined already, then it silently merges the existing documentation with the new one. The title of the group is optional for this command, so you can use
```
/** \addtogroup <label>
* @{
*/
...
/** @}*/
```
:::warning
compound entities (like classes, files and namespaces) can be put into multiple groups, but members (like variable, functions, typedefs and enums) can only be a member of one group
:::
The `\ref` command can be used to refer to a group. The first argument of the `\ref` command should be group's label. To use a custom link name, you can put the name of the links in double quotes after the label, as shown by the following example
```
This is the \ref group_label "link" to this group.
```
The priorities of grouping definitions are (from highest to lowest): `\ingroup`, `\defgroup`, `\addtogroup`, `\weakgroup`. The last command is exactly like `\addtogroup` with a lower priority. It was added to allow "lazy" grouping definitions: you can use commands with a higher priority in your .h files to define the hierarchy and `\weakgroup` in .c files without having to duplicate the hierarchy exactly.
Example:
```clike=
/** @defgroup group1 The First Group
* This is the first group
* @{
*/
/** @brief class C1 in group 1 */
class C1 {};
/** @brief class C2 in group 1 */
class C2 {};
/** function in group 1 */
void func() {}
/** @} */ // end of group1
/**
* @defgroup group2 The Second Group
* This is the second group
*/
/** @defgroup group3 The Third Group
* This is the third group
*/
/** @defgroup group4 The Fourth Group
* @ingroup group3
* Group 4 is a subgroup of group 3
*/
/**
* @ingroup group2
* @brief class C3 in group 2
*/
class C3 {};
/** @ingroup group2
* @brief class C4 in group 2
*/
class C4 {};
/** @ingroup group3
* @brief class C5 in @link group3 the third group@endlink.
*/
class C5 {};
/** @ingroup group1 group2 group3 group4
* namespace N1 is in four groups
* @sa @link group1 The first group@endlink, group2, group3, group4
*
* Also see @ref mypage2
*/
namespace N1 {};
/** @file
* @ingroup group3
* @brief this file in group 3
*/
/** @defgroup group5 The Fifth Group
* This is the fifth group
* @{
*/
/** @page mypage1 This is a section in group 5
* Text of the first section
*/
/** @page mypage2 This is another section in group 5
* Text of the second section
*/
/** @} */ // end of group5
/** @addtogroup group1
*
* More documentation for the first group.
* @{
*/
/** another function in group 1 */
void func2() {}
/** yet another function in group 1 */
void func3() {}
/** @} */ // end of group1
```
## membergroup
If a compound (e.g. a class or file) has many members, it is often desired to group them together. Doxygen already automatically groups things together on type and protection level, but maybe you feel that this is not enough or that that default grouping is wrong. For instance, because you feel that members of different (syntactic) types belong to the same (semantic) group.
A member group is defined by a
```
///@{
...
///@}
```
block or a
```
/**@{*/
...
/**@}*/
```
Before the opening marker of a block a separate comment block may be placed. This block should contain the `@name` (or `\name`) command and is used to specify the header of the group. Optionally, the comment block may also contain more detailed information about the group.
==Nesting of member groups is not allowed.==
If all members of a member group inside a class have the same type and protection level (for instance all are static public members), then the whole member group is displayed as a subgroup of the type/protection level group (the group is displayed as a subsection of the "Static Public Members" section for instance). If two or more members have different types, then the group is put at the same level as the automatically generated groups. If you want to force all member-groups of a class to be at the top level, you should put a `\nosubgrouping` command inside the documentation of the class.
Example:
```
/** A class. Details */
class Memgrp_Test
{
public:
//@{
/** Same documentation for both members. Details */
void func1InGroup1();
void func2InGroup1();
//@}
/** Function without group. Details. */
void ungroupedFunction();
void func1InGroup2();
protected:
void func2InGroup2();
};
void Memgrp_Test::func1InGroup1() {}
void Memgrp_Test::func2InGroup1() {}
/** @name Group2
* Description of group 2.
*/
///@{
/** Function 2 in group 2. Details. */
void Memgrp_Test::func2InGroup2() {}
/** Function 1 in group 2. Details. */
void Memgrp_Test::func1InGroup2() {}
///@}
/*! \file
* docs for this file
*/
//!@{
//! one description for all members of this group
//! (because DISTRIBUTE_GROUP_DOC is YES in the config file)
#define A 1
#define B 2
void glob_func();
//!@}
```
## subpaging
Information can be grouped into pages using the `\page` and `\mainpage` commands. Normally, this results in a flat list of pages, where the "main" page is the first in the list.
Instead of adding structure using the approach described in section modules it is often more natural and convenient to add additional structure to the pages using the `\subpage` command.
For a page A the `\subpage` command adds a link to another page B and at the same time makes page B a subpage of A. This has the effect of making two groups GA and GB, where GB is part of GA, page A is put in group GA, and page B is put in group GB.
# Including formulas(數學運算式)
<https://www.stack.nl/~dimitri/doxygen/manual/formulas.html>
# Graphs and diagrams
<https://www.stack.nl/~dimitri/doxygen/manual/diagrams.html>
# Searching
<https://www.stack.nl/~dimitri/doxygen/manual/searching.html>
# Customizing the output
## Navigation
By default doxygen shows navigation tabs on top of every HTML page, corresponding with the following settings:
```
DISABLE_INDEX = NO
GENERATE_TREEVIEW = NO
```
you can switch to an interactive navigation tree as sidebar using
```
DISABLE_INDEX = YES
GENERATE_TREEVIEW = YES
```
or even have both forms of navigation:
```
DISABLE_INDEX = NO
GENERATE_TREEVIEW = YES
```
if you already use an external index (i.e. have one of the following options enabled `GENERATE_HTMLHELP`, `GENERATE_ECLIPSEHELP`, `GENERATE_QHP`, or `GENERATE_DOCSET`) then you can also disable all indices, like so:
```
DISABLE_INDEX = YES
GENERATE_TREEVIEW = NO
```
## Dynamic Content
To make the HTML output more interactive, doxygen provides a number of options that are disabled by default:
enabling `HTML_DYNAMIC_SECTIONS` will make doxygen hide certain content (like graphs) in the HTML by default, and let the reader expand these sections on request.
enabling `HAVE_DOT` along with `INTERACTIVE_SVG` while setting `DOT_IMAGE_FORMAT `to svg, will make doxygen produce SVG images that will allow the user to zoom and pan (this only happens when the size of the images exceeds a certain size).
## Header, Footer, and Stylesheet changes
To tweak things like fonts or colors, margins, or other look & feel aspects of the HTML output in detail, you can create a different [cascading style sheet](https://www.w3schools.com/css/default.asp). You can also let doxygen use a custom header and footer for each HTML page it generates, for instance to make the output conform to the style used on the rest of your web site.
To do this first run doxygen as follows:
```
doxygen -w html header.html footer.html customdoxygen.css
```
This will create 3 files:
* `header.html` is a HTML fragment which doxygen normally uses to start a HTML page. Note that the fragment ends with a body tag and that is contains a couple of commands of the form $word. These will be replaced by doxygen on the fly.
* `footer.html` is a HTML fragment which doxygen normally uses to end a HTML page. Also here special commands can be used. This file contain the link to www.doxygen.org and the body and html end tags.
* `customdoxygen.css` is the default cascading style sheet used by doxygen. It is recommended only to look into this file and overrule some settings you like by putting them in a separate stylesheets and referencing those extra files via `HTML_EXTRA_STYLESHEET`.
You should edit these files and then reference them from the config file.
```
HTML_HEADER = header.html
HTML_FOOTER = footer.html
HTML_EXTRA_STYLESHEET = my_customdoxygen.css
```
:::info
it is not longer recommended to use `HTML_STYLESHEET`, ==as it make it difficult to upgrade to a newer version of doxygen.== Use `HTML_EXTRA_STYLESHEET` instead.
See the documentation of the `HTML_HEADER` tag for more information about the possible meta commands you can use inside your custom header.
:::
:::info
You should not put the style sheet in the HTML output directory. Treat it as a source file. Doxygen will copy it for you.
If you use images or other external content in a custom header you need to make sure these end up in the HTML output directory yourself, for instance by writing a script that runs doxygen can then copies the images to the output.
:::
## Changing the layout of pages
<http://www.stack.nl/~dimitri/doxygen/manual/customize.html>
# Linking to external documentation
To generate a tag file for your project, simply put the name of the tag file after the `GENERATE_TAGFILE` option in the configuration file.
To combine the output of one or more external projects with your own project you should specify the name of the tag files after the `TAGFILES `option in the configuration file.
```
<root>
+- proj
| +- html HTML output directory for proj
| +- src sources for proj
| |- proj.cpp
+- ext1
| +- html HTML output directory for ext1
| |- ext1.tag tag file for ext1
+- ext2
| +- html HTML output directory for ext2
| |- ext2.tag tag file for ext2
|- proj.cfg doxygen configuration file for proj
|- ext1.cfg doxygen configuration file for ext1
|- ext2.cfg doxygen configuration file for ext2
```
Then the relevant parts of the configuration files look as follows:
proj.cfg:
```
OUTPUT_DIRECTORY = proj
INPUT = proj/src
TAGFILES = ext1/ext1.tag=../../ext1/html \
ext2/ext2.tag=../../ext2/html
```
ext1.cfg:
```
OUTPUT_DIRECTORY = ext1
GENERATE_TAGFILE = ext1/ext1.tag
```
ext2.cfg:
```
OUTPUT_DIRECTORY = ext2
GENERATE_TAGFILE = ext2/ext2.tag
```
# Automatic link generation
http://www.stack.nl/~dimitri/doxygen/manual/autolink.html
# doxgen config
## config file
```
PROJECT_NAME = PROJECT_NAME
PROJECT_NUMBER = 1.0
OUTPUT_DIRECTORY = ../docs
CREATE_SUBDIRS = YES
EXTRACT_ALL = YES
OUTPUT_LANGUAGE = Chinese-Traditional # default: English
FULL_PATH_NAMES = NO # default: YES
EXTRACT_STATIC = YES # default: NO
FILE_PATTERNS = *.php
RECURSIVE = YES # default: NO
REFERENCED_BY_RELATION = YES # default: NO
REFERENCES_RELATION = YES # default: NO
```
* PROJECT_NAME：當然要改成自己的名字
* OUTPUT_DIRECTORY：我設定在 doc 資料夾，並且把 doc 資料夾加到 .git 中
* OUTPUT_LANGUAGE：設定語言
* EXTRACT_ALL：設成 YES，這樣才會解析所有的檔案，否則必須要用 \file 或 @file 定義過的檔案才會被解析，否則它只會解析 .h 檔
* INPUT：用空白分隔的輸入檔案或資料夾，我是 src 資料夾
* FILE_PATTERNS：設定要分析的檔案，這裡我只保留 .c 跟 .h
* EXCLUDE：把不需要的資料夾剔掉，因為我有一個測試的 test 資料夾，所以把它加上去
* GENERATE_*：設定要輸出的格式，我只選擇輸出 html ，設定 GENERATE_HTML 是 YES
* INLINE_SOURCE = YES
Extract the relevant parts of the source and associate them with your description.
* HAVE_DOT = YES
Use Graphviz for class and collaboration diagrammes.
* CALL_GRAPH = YES
Generate a dependency graph for functions and methods.
* GENERATE_LATEX = NO
Skip generating LaTeX sources for PDF.
# doxygen usage
To generate a manual for your project you typically need to follow these steps:
1. You document your source code with special documentation blocks (see section Special comment blocks).
2. You generate a configuration file (see section Configuration) by calling doxygen with the -g option:
```
doxygen -g <config_file>
```
3. You edit the configuration file so it matches your project. In the configuration file you can specify the input files and a lot of optional information.
4. You let doxygen generate the documentation, based on the settings in the configuration file:
```
doxygen <config_file>
```
* If you have a configuration file generated with an older version of doxygen, you can upgrade it to the current version by running doxygen with the -u option.
```
doxygen -u <config_file>
```
# 範例
```clike
#include <stdio.h>
/**
* \file manual.c
*/
typedef struct Object Object; //!< Object type
typedef struct Vehicle Vehicle; //!< Vehicle type
typedef struct Car Car; //!< Car type
typedef struct Truck Truck; //!< Truck type
/*!
* Base object class.
*/
struct Object {
int ref; //!< \private Reference count.
};
/*!
* Increments object reference count by one.
* \public \memberof Object
*/
static Object * objRef(Object *obj);
/*!
* Decrements object reference count by one.
* \public \memberof Object
*/
static Object * objUnref(Object *obj);
/*!
* Vehicle class.
* \extends Object
*/
struct Vehicle {
Object base; //!< \protected Base class.
};
/*!
* Starts the vehicle.
* \public \memberof Vehicle
*/
void vehicleStart(Vehicle *obj);
/*!
* Stops the vehicle.
* \public \memberof Vehicle
*/
void vehicleStop(Vehicle *obj);
/*!
* Car class.
* \extends Vehicle
*/
struct Car {
Vehicle base; //!< \protected Base class.
};
/*!
* Truck class.
* \extends Vehicle
*/
struct Truck {
Vehicle base; //!< \protected Base class.
};
/* implementation */
void vehicleStart(Vehicle *obj)
{
if (obj) printf("%x derived from %x\n", obj, obj->base);
}
/*!
* Main function.
*
* Ref vehicleStart(), objRef(), objUnref().
*/
int main(void)
{
Car c;
vehicleStart((Vehicle*) &c);
}
```
設定檔:
```
PROJECT_NAME = "Manual inheritance and membership"
OUTPUT_DIRECTORY = doc
GENERATE_LATEX = NO
GENERATE_MAN = NO
GENERATE_RTF = NO
CASE_SENSE_NAMES = NO
INPUT = manual.c
QUIET = YES
JAVADOC_AUTOBRIEF = YES
EXTRACT_PRIVATE = YES
EXTRACT_STATIC = YES
TYPEDEF_HIDES_STRUCT = YES
INLINE_SOURCES = YES
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION = YES
SEARCHENGINE = NO
COMPACT_LATEX = YES
LATEX_HIDE_INDICES = YES
```
makefile:
```
doc:
@doxygen
```
# doxywizard 利用gui來設定doxygen
```
$ sudo apt install doxygen-gui
```
Sign in with Wallet
Connect another wallet