Doxygen documentation

zhaozj2021-02-16  52

Add a comment after MEMBERS

If you need to add a comment for the MEMBERS of File, Struct, Union, Class or ENMU, and you need to release these NOTED within Compound, you can consider putting the comment block behind the Member. This will add a "<" tag to the comment block.

Here is an example:

Int var; / *!

This block is used to add an annotation block after a member (QT style)

There is also a way

Int var; / **

or it could be

Int var; //!

//! <

or it could be

int var; ///

/// <

In most cases, just add a Brief description after a member, as follows:

Int var; //!

or

Int var; ///

Note that these blocks have the same structure, but it is used

Here is an example of using an comment block:

/ *! A Test class * /

Class test

{

PUBLIC:

/ ** an enum type.

* The Documentation Block Cannot Be Put Af!

* /

ENUM ENUMTYPE

{

Int Eval1, / **

INT Eval2 / **

}

Void Member (); //!

protected:

Int value; / *!

}

Click Hered The Corresponding Html Documentation That IS generated by doxygen.

caveat:

These blocks can only be used for Member and Parameters comments. You cannot add comments to Files, Classes, Unions, StruCTS, Groups, Namespaces, and Enums. There is also the Structural Commands discussed in the next section, is ignored in this comment block.

Documentation At Other Places

As of now, the comment block we talk is before and after the Declaration or Definition of File, Class or Namespace. Although this usually has reached the purpose, it is sometimes released in other places. It is also necessary to add a comment for a file, but there is no "before the file". Doxygen allows the comment block to be placed elsewhere (also not allowed: For example, in a function or a standard C-style comment block).

This is more troublesome that needs to add some structural commands in the comment block.

Structual Commands (like other commands) starts with "/", or a "@" (using the Javadoc style), followed by the command name and one or more parameters. For example, if you want to add a comment to the Test class above: / *! / Class test

/ brief a test class.

A more detailed class description.

* /

This special command "/ class" is used to indicate a comment containing the Test class in the comment block. There are some other structural commands:

· / Struct to document a c-structure.

· / UNION TO Document a Union.

· / Enum to document an enumeration type.

· / Fn to document a function.

· / Var to Document a variable or typedef or enum value.

· / Def to document a #define.

· / File to Document A File.

· / Namespace to Document a namespace.

· / Package to document a java package.

· / Interface to document an id1 interface.

Get more detailed information on Special Commands.

In order to comment on the Member in a class, you must first comment on this class. The same problem rises to Namespace. To comment a global Function, TypeDef, Enum or PreProcessor definition, you need to first define a file containing it (usually a .h file because these files contain information that can be export to other source files).

Let's repeat, because it is often ignored: to comment a global objects (functions, typedefs, enum, macros, etc.), you must comment .h file. In other words, at least you should notice this.

/ *! / file * /

Or such a

/ ** @file * /

Row in this file

Here is a C header name called Structcmd.h, explaining how to use Structal Commands.

/ *! / file structcmd.h

/ brief a docute file.

Details.

* /

/ *! / def MAX (a, b)

/ brief a macro tria returns the maximum of / a a a a a a a a a a

Details.

* /

/ *! / var typedef unsigned int uint32

/ brief a type definition for a.

Details.

* /

/ *! / var int rt errno

/ brief contains the last error code.

/ WARNING NOT Thread Safe!

* /

/ *! / fn int open (const char * pathname, int flags)

/ brief Opens a file descriptor.

/ Param Pathname The name of the descriptor.

/ param flags opening flags.

* /

/ *! / fn int close (int FD)

/ brief closs the file descriptor / a fd.

/ Param fd the descriptor to close. * /

/ *! / fn size_t write (int FD, Const Char * buf, size_t count)

/ brief Writes / a count bytes from / a buf to the filedescriptor / a fd.

/ Param fd the descriptor to write.

/ Param buf the data buffer to write.

/ Param Count the number of bytes to write.

* /

/ *! / fn int in (int FD, Char * BUF, SIZE_T COUNT)

/ brief read bytes from a file descriptor.

/ Param fd the descriptor to read from.

/ param buf the buffer to read in.

/ Param Count the number of bytes to read.

* /

#define max (A, B) (((a)> (b))? (a) :( b))

Typedef unsigned int uint32;

Int errno;

INT OPEN (const char *, int);

INT Close (int);

SIZE_T WRITE (int, const char *, size_t);

INT Read (int, char *, size_t);

Click Hered The Corresponding Html Documentation That IS generated by doxygen.

Because each comment block in the example above contains a structural command, all the comment blocks could be moved to another location or input file (the source file for instance), without affecting the generated documentation. The disadvantage of this approach is that prototypes are duplicated , so all changes have to be made twice! Because of this you should first consider if this is really needed, and avoid structural commands if possible. I often receive examples that contain / fn command in comment blocks which are place in front of a function .............. ..

Because each of the foresses contains a structured command, all comments can be placed in other locations or input files (such as Source File), and will not be generated by video documents. The disadvantage of this approach is that the prototype is copied, so every time you have to write twice. Because of this, you should first consider whether it is necessary and avoids Structural Commands as much as possible. I often receive this file, there is a "/ fn" command in the comment before a function. This is redundant, causing an error.


New Post(0)