代码注释及Doxygen文档生成
1、Doxygen
Doxygen是一个免费的（成本和许可证）工具，可读取源代码，查找遵循特定条件的注释。构建并从注释和代码中提取信息以生成文档。 它以多种格式输出：HTML，RTF（富文本格式），LaTeX，UNIX手册页和XML。
Java程序员可能熟悉类似的名为javadoc的工具。Javadoc工具是Java软件开发工具包中的标准工具，而Doxygen与C ++标准或任何C ++供应商都没有关系。C++缺乏结构化文档的标准，因此你可以自由地做任何想做的事情。例如，如果你计划完全在Microsoft .NET环境中工作，Microsoft会在注释中为XML标签定义自己的约定，这很好。对于其他程序员，建议使用具有更广泛和可移植性的工具。最受欢迎的解决方案是Doxygen，我认为即使你决定不使用它，每个C ++程序员也应该知道这一点。
2、结构化内容
Doxygen遵循特定格式的注释。
- 单行注释以一个额外的斜杠或感叹号开头：///或//！
- 多行注释以一个额外的星号或感叹号开头：/ **或/ *！
同样，Doxygen认识到一些广泛使用的注释约定和修饰。例如。它忽略一行的斜线。例如：
多行注释可以从一个充满星号的行开始。例如：
/**************************************************************
And a line in a multiline comment can begin with an asterisk.
/*************************************************************
This is a structured comment for Doxygen.
*************************************************************/
在结构化注释中，您可以记录程序中的各种实体：函数，类型，变量等。
按照惯例，声明或定义之前的注释适用于要声明或定义的实体。 有时希望在声明后加上注释，例如对变量的单行描述。 为此，请在注释内容的开头使用“小于”（<）符号。
double const c = 299792458.0; ///< speed of light in m/sec
3、文档标签和Markdown
Doxygen常用的标记如下：
- @b word： 用黑体字标记单词。还可以使用HTML标记word</ b>，当短语包含空格，或使用Markdown，将文本括在星号中：
*word*。 - @brief one-sentence-description：简要描述一个实体，相当于摘要。 实体具有简短详细的文档。根据配置Doxygen的方式，简要文档可以是实体完整文档的第一句话，也可以要求提供明确的文档**@brief**标签。 无论哪种情况，其余的内容都是该实体的详细文档。
- @c word：将word视为代码片段，并将其设置为固定间距的字体。还可以使用HTML标记，短语</ tt>，或对Markdown使用反引号
word。 - @em word：强调用斜体字。还可以使用HTML标签，word</ em>或Markdown的下划线：word。
- @file file name：提供源文件的概述。 详细说明可以描述文件的用途，修订历史，和其他全球文档。 文件名是可选的；没有它，Doxygen将使用文件的真实名称。
- @link entity text @endlink：创建指向命名实体（例如文件）的超链接。
- @mainpage title：提供索引或封面整个项目的概述。可以将@mainpage放在任何源文件中，甚至可以为注释保留一个单独的文件。 在小型项目中，可以将@mainpage放在与main函数相同的源文件中，但是在大型项目中，建议使用单独的文件。
- @p name：在固定间距字体中设置name，以将其区分为功能参数。
- @par title：始一个新段落。如果提供单行标题，它将成为段落标题。空白行也分隔段落。
- @param name description：记录一个名为name的函数参数。 如果您想在函数的其他地方引用此参数文档，请使用**@p name**。
- @post postcondition：记录函数的后置条件。 后置条件是一个布尔表达式，您可以假定它为true函数返回时（假设所有前提均成立）。 C ++缺乏任何强制的正式机制后置条件（而不是断言），因此记录后置条件至关重要，尤其是对于库编写者而言。
- @pre precondition：记录函数的前提条件。前提条件是布尔表达式，在该函数之前必须为真被调用，否则不能保证该功能正常工作。 C ++缺乏任何强制的正式机制前提条件（而不是断言），因此记录前提条件至关重要，尤其是对于库编写者而言。
- @return description：记录函数的返回值描述。
- @see xref：插入对名为外部参照的实体的交叉引用。Doxygen寻找对内部其他文档化实体的引用结构化注释。 找到一个时，它会插入一个超链接（或文本交叉引用，具体取决于输出格式）。 但是，有时必须插入对未在实体中命名的实体的显式引用文档，因此可以使用@see。还可以通过在名称前加上％来禁止自动创建超链接。
- @&, @@, @, @%, @<：转义文字字符（＆，@，\，％或<），以防止被Doxygen或HTML解释。
Doxygen非常灵活，可以使用多种方式使用本机Doxygen标签格式化注释，HTML或Markdown。示例如下：
/** @file
* @brief Test strings to see whether they are palindromes.
* Read lines from the input, strip non-letters, and check whether
* the result is a palindrome. Ignore case differences when checking.
* Echo palindromes to the standard output.
*/
/** @mainpage Palindromes
* Test input strings to see whether they are palindromes.
*
* A _palindrome_ is a string that reads the same forward and backward.
* To test for palindromes, this program needs to strip punctuation and
* other non-essential characters from the string, and compare letters without
* regard to case differences.
*
* This program reads lines of text from the standard input and echoes
* to the standard output those lines that are palindromes.
*
* Source file: [palindrome.cpp](palindrome.cpp)
*
* @date 27-July-2013
* @author Ray Lischner
* @version 2.0
*/
#include <algorithm>
#include <iostream>
#include <iterator>
#include <locale>
#include <string>
/** @brief Test for non-letter.
* Test the character @p ch in the global locale.
* @param ch the character to test
* @return true if @p ch is not a letter
*/
bool non_letter(char ch)
{
return not std::isalnum(ch, std::locale{});
}
/** @brief Convert to lowercase.
* Use a canonical form by converting to uppercase first,
* and then to lowercase. This approach does not solve the eszet
* problem (German eszet is a lowercase character that converts
* to two uppercase characters), but it's the best we can do in
* standard C++.
*
* All conversions use the global locale.
*
* @param ch the character to test
* @return the character converted to lowercase
*/
char lowercase(char ch)
{
return std::tolower(ch, std::locale{});
}
/** @brief Compare two characters without regard to case.
* The comparison is limited by the `lowercase()` function.
* @param a one character to compare
* @param b the other character to compare
* @return `true` if the characters are the same in lowercase,
* `false` if they are different.
*/
bool is_same_char(char a, char b)
{
return lowercase(a) == lowercase(b);
}
/** @brief Determine whether @p str is a palindrome.
* Only letter characters are tested. Spaces and punctuation don't count.
* Empty strings are not palindromes because that's just too easy.
* @param str the string to test
* @return `true` if @p str is the same forward and backward and
* `not str.empty()`
*/
bool is_palindrome(std::string str)
{
std::string::iterator end{std::remove_if(str.begin(), str.end(), non_letter)};
std::string rev{str.begin(), end};
std::reverse(rev.begin(), rev.end());
return not rev.empty() and std::equal(str.begin(), end, rev.begin(), is_same_char);
}
/** @brief Main program.
* Set the global locale to the user's native locale. Then imbue the I/O streams
* with the native locale.
*/
int main()
{
std::locale::global(std::locale{""});
std::cin.imbue(std::locale{});
std::cout.imbue(std::locale{});
std::string line{};
while (std::getline(std::cin, line))
if (is_palindrome(line))
std::cout << line << '\n';
}
生成文档如下：
