使用doxygen记录代码的最佳提示？ [英] Best Tips for documenting code using doxygen?

问题描述

我的团队开始使用doxygen记录我们的C代码，特别注意我们的公共API标头。在doxygen中似乎有很多灵活性和不同的特殊命令，这是很好的，但不清楚什么是好事，什么是坏事没有试错。

你最喜欢的方法是标记你的代码，你必须做什么和不要做什么？

请提供你的顶尖技巧，每个答案一个方便投票。 / p>

我希望定义我们整个API文档的方法，包括提供一个模板，让其他团队开始。到目前为止，我有这样的东西：

  / ** 
 * @file example_action.h 
 * @Author Me（[e-mail]）
 * @date 2008年9月
 * @brief文件简要说明。 
 * 
 *文件详细说明。 
 * / 
 
 / ** 
 * @name示例API操作
 * @brief可用的示例操作。 
 * @ingroup示例
 * 
 *此API提供某些操作作为示例。 
 * 
 * @param [in] repeat不执行任何操作的次数。 
 * 
 * @retval TRUE成功没有做任何事情。 
 * @retval FALSE糟糕，做了一些事情。 
 * 
 *示例用法：
 * @code 
 * example_nada（3）; //不要做3次
 * @endcode 
 * / 
布尔示例（int repeat）; 
  

解决方案

你不需要，不应该写名字的文件在 @file 指令中，doxygen会自动读取文件的名称。编写文件名称的问题是，当您重命名文件时，您将不得不更改 @file 指令。

提供 @author 和 @date 信息在源代码控制之后的大部分时间也是无用的系统比手动编辑文件好多了。

如果您使用以下Doxygen语法并启用了doxygen的JAVADOC_AUTOBRIEF，那么您也不需要编写 @brief 配置：

  / *！第一行的简短描述
 
详细描述... 
 ... 
 * / 
 void foo（void）{} 
  

函数的 @name 指令大部分时间也是100％冗余并完全无用。只有当某人修改函数的名称而不是doxygen @name 时，才会出现错误。

My team is starting to document our C code using doxygen, paying particular attention to our public API headers. There appears to be a lot of flexibility and different special commands in doxygen, which is great, but it's not clear what's a good thing and what's a bad thing without trial and error.

What are your favourite ways to mark up your code, what are your MUST DOs and DO NOTs?
Please provide your top tips, one per answer to facilitate voting.

I am looking to define our whole approach to API documentation, including providing a template to get the rest of the team started. So far I have something like this:

/**
 * @file   example_action.h
 * @Author Me ([e-mail])
 * @date   September, 2008
 * @brief  Brief description of file.
 *
 * Detailed description of file.
 */

/**
 * @name    Example API Actions
 * @brief   Example actions available.
 * @ingroup example
 *
 * This API provides certain actions as an example.
 *
 * @param [in] repeat  Number of times to do nothing.
 *
 * @retval TRUE   Successfully did nothing.
 * @retval FALSE  Oops, did something.
 *
 * Example Usage:
 * @code
 *    example_nada(3); // Do nothing 3 times.
 * @endcode
 */
boolean example(int repeat);

解决方案

You don't need and should not write the name of the file in the @file directive, doxygen reads the name of the file automatically. The problem with writing the name of the file is that when you rename the file you will have to change the @file directive as well.

Providing @author and @date information is also useless most of the time since the source control system does it a lot better than someone editing the files manually.

You also don't have to write @brief if you use the following Doxygen syntax and enable JAVADOC_AUTOBRIEF in doxygen's configuration:

/*! Short Description on the first line

    Detailed description...
    ...
*/
void foo(void) {}

The @name directive for functions is also 100% redundant most of the time and completely useless. It only brings errors when someone modifies the name of the function and not the doxygen @name.

这篇关于使用doxygen记录代码的最佳提示？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！