Use Javadoc style annotations to let Doxygen automatically generate documents

Source: Internet
Author: User
Tags documentation doxygen reserved
Writing comments for code has been a bit of a problem for most developers. Current developers can accept the idea of writing annotations for program maintainability and readability, but many developers still don't have answers about where to write comments, how to write notes, how much to write, and so on. More headaches are writing documents and maintaining documentation, and developers can often tolerate writing or modifying the corresponding annotations when writing or altering the code, but it is difficult to fix the document later. It is undoubtedly a boon to developers if they can be translated directly from annotations into documents. Doxygen can automatically translate notes that follow a certain format into the corresponding document.

Doxygen is a GPL based open source project and is a very good document system that is currently running on most Unix (including Linux), Windows family, Mac systems, full support for C + +, C, Java, IDL (CORBA and Microsoft Family) language, partially supported in PHP and C # languages, output formats include HTML, latex, RTF, PS, PDF, compressed HTML, and Unix manpage. There are many open source projects, such as Log4cpp and Cppunit, that use the Doxygen document System.

Doxygen is one such tool. When you write a comment, follow some of the rules that it has set up slightly. Then he will be able to help you produce a beautiful document. Therefore, the use of Doxygen can be divided into two parts. The first is the writing of annotations in a particular format, and the second is the use of Doxygen tools to produce files.

Download of Doxygen and related tools

(1) The latest version of Doxygen can be downloaded from Doxygen's website.

(2) Graphviz is a graphical visualization software. Doxygen uses Graphviz to generate a variety of graphics, such as class inheritance diagrams, collaboration diagrams, header files, and so on. The latest version of Graphviz can be downloaded from the Graphviz Web site.

Introduction to common instructions

@file

Annotation description of the file.

@author

Author's information

@brief

A simple description for class or function

eg

@brief This function is responsible for printing the error message string

@param

Mainly used in function descriptions, followed by the name of the parameter, and then the description of the parameter

@return

Describes the return value of this function

eg

@return This function returns the execution result, returns true if successful, otherwise returns flase

@retval

Describe the return value type

eg

@retval null-empty string.
@retval! Null Non-empty string.

@note

Annotations

@attention

Attention

@warning

Warning message

@enum

An enumeration is referenced, and Doxygen produces a link at the enumeration.

eg

@enum Ctest::myenum

@var

A variable is referenced, and Doxygen produces a link at the enumeration.

eg

@var Ctest::m_filekey

@class

Referencing a class,

Format: @class <name> [

eg

@class ctest "Inc/class.h"

@exception

Description of possible exceptions

eg

@exception This function may produce an exception that is out of range

/** * @file testcommnet.h * @brief * @author liuxuezong * @date 2011/8/24 8:37:56 * @version 0.1 * <pre><b>co pyright:microsoft</b></pre> * <pre><b>email: </b>liuxuezong@126.com</pre> * <pre><b>company: </b>http://www.microsoft.com</pre> * <pre><b>all rights reserved.</b></pre>/#ifndef _testcommnet_h_ #define _TESTCOMMNET_H_/** * @class ctestcommnet * @brief a simple
Javadoc Documentation Annotation example.
* * This example contains annotations such as enumerations, classes, functions, variables, and so on.  * */** The enumeration definition of color * * This enumeration defines the colors that are needed in the system \ n * You can use this enumeration as the identity of the color in the system/enum Tenum {red,/**< red */Blue,/**< blue */Yellow/**< yellow.    

*/} Enumvar;
	Class Ctestcommnet {public:/** * @brief constructor for Ctestcommnet.
	* * Detailed description.

	* * Ctestcommnet ();
	/** * @brief destructor for ctestcommnet.
	* * Detailed description.

* * Virtual ~ctestcommnet (); Public:/** * @brief ADD * * via formal parameter Aand b sum.
	* @param [in] parameter A * @param [in] parameter b * @return int * @retval returns the a+b.

*/int Add (int a, int b); Protected:int M_ncount;

/**< count variable */}; #endif//_testcommnet_h_

#include "testcomment.h"

ctestcommnet::ctestcommnet ()
{
	m_ncount = 0;
}

Ctestcommnet::~ctestcommnet ()
{
}

int Ctestcommnet::add (int a, int b)
{return
	(A + b);
}

f:/test/testcommnet.h File Reference


Combination Type
Class Ctestcommnet
A simple Javadoc documentation annotation example. More ...

Enumeration
Enum Tenum {red,blue, yellow}

variable
Enum Tenum Enumvar
Detailed Description Author: liuxuezong Date: 2011/8/24 8:37:56 version: 0.1
  copyright:microsoft  
  Email:  liuxuezong@126.com 
  Company:  http://www.microsoft.com 
  All rights reserved.  
Enumerate type Documents
enum tenum

Enumeration definition for color

This enumeration defines the colors that are needed in your system
to use this enumeration as the identity of the colors in your system enumeration values:

red 
; Red
blue  Blue
yellow  yellow.

variable document

enum Tenum Enumvar

Color Enumeration Definition

This enumeration defines the colors that need to be used on the system
You can use this enumeration as the identity of the colors in the system

The ctestcommnet class refers to a simple Javadoc documentation annotation example. More ...

#include <testcommnet.h>

A list of all members.


Public Members
Ctestcommnet ()
Constructor for Ctestcommnet.
Virtual ~ctestcommnet ()
destructor for Ctestcommnet.
Int ADD (int A, int b)
ADD

Protection Properties
Int M_ncount
Detailed DescriptionA simple Javadoc documentation annotation example.

The example contains annotations such as enumerations, classes, functions, variables, and so on. Construction and destructor document

Ctestcommnet::ctestcommnet ( )

Constructor for Ctestcommnet.

Detailed description.

Ctestcommnet::~ctestcommnet ( ) [Virtual]

destructor for Ctestcommnet.

Detailed description.

member function Document

int Ctestcommnet::add ( Int A
Int B
)

Add

Sum by formal parameters A and B. Parameters:

[In] Formal parameter A
[In] Formal parameter B
return:Intreturn Value:
Returns the A+b and.

member Data Document

int Ctestcommnet::m_ncount [protected]

Count variable

The document for this class is generated by the following file: F:/test/testcommnet.h f:/test/testcommnet.cpp

Finally, thank you for reading, more details can be searched online:)

Contact Us

The content source of this page is from Internet, which doesn't represent Alibaba Cloud's opinion; products and services mentioned on that page don't have any relationship with Alibaba Cloud. If the content of the page makes you feel confusing, please write us an email, we will handle the problem within 5 days after receiving your email.

If you find any instances of plagiarism from the community, please send an email to: info-contact@alibabacloud.com and provide relevant evidence. A staff member will contact you within 5 working days.

A Free Trial That Lets You Build Big!

Start building with 50+ products and up to 12 months usage for Elastic Compute Service

  • Sales Support

    1 on 1 presale consultation

  • After-Sales Support

    24/7 Technical Support 6 Free Tickets per Quarter Faster Response

  • Alibaba Cloud offers highly flexible support services tailored to meet your exact needs.