如何注释你的文档doxygen版

本篇文章翻译自

http://www-numi.fnal.gov/offline_software/srt_public_context/WebDocs/doxygen-howto.html

为了使阅读增加对比性，这里把原文也摘录过来，一边摘录一边翻译。

How to document your code fordoxygen

Note there are some emacslisp macros that will help do a lot of what is described here.

本句不理解，略。

Doing nothing, Doxygen will produce a nice cross referenced HTML-izedversion of the code. However, you can make this even more useful by embeddingdocumentation on how to use your classes right in the code itself. It is veryeasy to learn the extension to C++ comments that doxygen uses. Several stylesare supported, see Doxygen's home pagefor more info, particularly thissection for details, but an adequate subset are reproduced here.

首先，Doxygen在不做任何额外的工作下可以很容易地把我们的代码生成相应的HTML格式的文档。然而，你也可以通过嵌入类似如何使用你声明过的类的用法的注释使之更有用。学习Doxygen的C++注释方法很容易。有很多注释的格式可以被Doxygen认同，参见Doxygen的官网，尤其是这个部分，当然也仅仅是一个子集而已。

1. Comments can come before the code item.
2. For class members and parameters they may also come after them.
3. They may be either brief (one line) or detailed or both.
4. Put the reference documentation type comments (class and method descriptions) in the .h file and not in (or, at least, in addition to) the .cxx files.

1)   在代码之前注释，

2)   针对类的成员和参数，注释也可以在其后面，

3)   注释有两种方式：简单的（一行）或者详细的或者两者都有，

4)   把类型代码的注释（类和用法描述）放在.h文件里，而不是在实现文件（.cxx）里。

Brief comment before

Add an extra "/"

    /// This method does something

void DoSomething();

代码前的简要注释

加一个额外的‘/’

   /// This method does something

void DoSomething();

Detailed comment before

Add an extra "*"

    /** This is a method that does so

      * much that I must write an epic 

      * novel just to describe how much

      * it truly does. */

    void DoNothing();

- the intermediate leading "*"s are optional.

代码前的详细注释

加一个额外的‘*’

/** This is a method that does so

  * much that I must write an epic 

  * novel just to describe how much

  * it truly does. */

void DoNothing();

中间注释置顶的‘*’可有可无。

Brief comment after

Add an extra "/<"

void DoSomething(); ///< This method does something

代码后的简要注释

加额外的‘/<’

void DoSomething(); ///< This method does something

Detailed comment after

Add an extra "*<"

    void DoNothing(); /**< This is a method that does so

      * much that I must write an epic 

      * novel just to describe how much

      * it truly does. */

- the intermediate leading "*"s are optional.

代码前的详细注释

加额外的‘*<’

void DoNothing(); /**< This is a method that does so

      * much that I must write an epic 

      * novel just to describe how much

      * it truly does. */

中间注释置顶的‘*’可有可无。

Modules or Packages

You can group a package worth of things using a singleinstance of "\defgroup". A good location for this is the LinkDef.hfile if the package has one. It might look something like:

/** \defgroup PackageName PackageTitle

 *

 * \brief Provide some stuff to do stuff

 */

Then in all the .h openning comments (see below) add a linelike:

/** ...

 *

 * \ingroup PackageName

 *

 * ...

 */

这段不大理解，那位看官有啥见解？欢迎点评。

Example .h file

Below is a full example.

/**
 * \class ExampleClass
 *
 * \ingroup PackageName
 * (Note, this needs exactly one \defgroup somewhere)
 *
 * \brief Provide an example
 *
 * This class is meant as an example.  It is not useful by itself
 * rather its usefulness is only a function of how much it helps
 * the reader.  It is in a sense defined by the person who reads it
 * and otherwise does not exist in any real form. 
 *
 * \note Attempts at zen rarely work.
 *
 * \author (last to touch it) $Author: bv $
 *
 * \version $Revision: 1.5 $
 *
 * \date $Date: 2005/04/14 14:16:20 $
 *
 * Contact: bv@bnl.gov
 *
 * Created on: Wed Apr 13 18:39:37 2005
 *
 * $Id: doxygen-howto.html,v 1.5 2005/04/14 14:16:20 bv Exp $
 *
 */

#ifndef EXAMPLECLASS_H
#define EXAMPLECLASS_H

class ExampleClass
{

public:

    /// Create an ExampleClass
    ExampleClass();

    /// Create an ExampleClass with lot's of intial values
    ExampleClass(int a, float b);

    ~ExampleClass();

    /// This method does something
    void DoSomething();

    /** This is a method that does so
      * much that I must write an epic 
      * novel just to describe how much
      * it truly does. */
    void DoNothing();

    /** \brief A useful method.
      * \param level an integer setting how useful to be
      * \return Output that is extra useful
      * 
      * This method does unbelievably useful things.  
      * And returns exceptionally useful results.
      * Use it everyday with good health.
      */
    void* VeryUsefulMethod(bool level);

private:

    const char* fQuestion; ///< the question
    int fAnswer;           ///< the answer 

};                              // end of class ExampleClass

#endif  // EXAMPLECLASS_H

Tags quick overview

Here are some of the most common tags, but I invite you to check the command list reference.

• Inform author for class, method, function, file...

@author

• Add a bug. A separated bug page can be later generated with links

@bug

• Inform date for class, method, function, file...

@date

• Put some source code between those 2 tags. Notice that the syntax is automatically highlighted

@code

@endcode

• File documentation.

@file

• With this tag you can write text for the main page, add section, subsection, :paragraph... Latex users will find some similarities here.

@mainpage

@section

@subsection

@subsubsection

@paragraph

@...

• Package documentation.

@package

• Method, function parameter documentation

@param

• Method, function return value documentation

@return

• Add a todo task. A separated todo page can be later generated with links

@todo

• Inform version for class, method, function, file...

@version

• Add a warning. A separated warning page can be later generated with links

@warning