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

问题描述

我的团队已经开始记录我们的C code。使用doxygen的，要特别注意我们的公共API头。似乎有很大的灵活性，并在doxygen的，这是很大的不同的特殊命令，但是目前还不清楚什么是一件好事，什么是没有试错坏事。

什么是您最喜欢的方式来标记你的code，你有什么必到之处和DO穷人？

请提供您顶级技巧，每回答一个方便的投票。

我期待来定义我们的整个方法的API文档，包括提供一个模板来获得团队的其他成员开始。到目前为止，我有这样的事情：

  / **
 * @file example_action.h
 * @author我（[e-mail]）
 * @date 2008年9月
 *文件的@brief简要说明。
 *
 *文件的详细描述。
 * // **
 * @name示例API操作
 * @brief提供示例操作。
 * @ingroup例子
 *
 *此API提供某些动作，例如，
 *
 * @参数[IN]的时候什么也不做，重复次数。
 *
 * @retval TRUE成功也没做。
 * @retval FALSE哎呀，做了什么。
 *
 *使用示例：
 * @ code
 * example_nada（3）; //什么都不做3次。
 * @结束code
 * /
例如布尔（INT重复）;
 

解决方案

写描述主页使用@mainpage（仅仅用于此目的的独立的头文件）。考虑，如在我的例子，使其成为引导到您的主类/功​​能和模块。

另一个样品

虽然我回来在网上获得上述联主oofile doxygen的内容，下面是使用Markdown格式目前的一些客户工作的例子。使用降价，你可以参考炫魅于降价（在Doxygen的设置），这是伟大的典型 readme.md 文件包含在开放源代码项目。

Lingopal
========
开发者文档开始当安迪登特接手支持2014年5月。有许多在降价格式页这解释关键方面： - @ref DOC / LingopalBuilding.md
- @ref DOC / LingopalSigning.md
- @ref DOC / LingopalDatabases.md
- @ref DOC / LingopalExternals.md见的＆lt; A HREF =pages.html＆GT;相关页面列表详情＆lt; / A＆GT;-------------_注意_这些页面，而可读本身，旨在通过[Doxygen的（http://www.doxygen.com）code文档它建立文档的整个本地交叉引用集发动机运行。它采用了轻微[降价格式的扩展。（http://www.stack.nl/~dimitri/doxygen/manual/markdown.html）生成文档的设置是`Lingopal.doxy`和`LingopalDocOnly.doxy`。后者是用于快速重新生成的只是这些附加页面。


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);

解决方案

Write a descriptive home page using @mainpage (in a separate header file just for this purpose). Consider, as shown in my example, making it a guide to your main classes/functions and modules.

Another Sample

Whilst I was getting the above-linked main oofile doxygen content back online, here's an example from some current client work using Markdown format. Using Markdown you can refer to a mainpage in markdown (in the Doxygen settings) which is great for the typical readme.md file included in open-source projects.

Lingopal
========
Developer Documentation started when Andy Dent took over support in May 2014. 

There are a number of pages in Markdown format which explain key aspects:

- @ref doc/LingopalBuilding.md
- @ref doc/LingopalSigning.md
- @ref doc/LingopalDatabases.md
- @ref doc/LingopalExternals.md

See the <a href="pages.html">Related Pages list for more.</a>

-------------

_Note_

These pages, whilst readable by themselves, are designed to be run through the [Doxygen](http://www.doxygen.com) code documentation engine which builds an entire local cross-referenced set of docs. It uses a minor [extension of Markdown formatting.](http://www.stack.nl/~dimitri/doxygen/manual/markdown.html)

The settings to generate the documentation are `Lingopal.doxy` and `LingopalDocOnly.doxy`. The latter is used for quick re-generation of just these additional pages.

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