Last active
May 8, 2018 07:18
-
-
Save mazhar-ansari-ardeh/7a17614f58b1b9a7026c07b27e4d9305 to your computer and use it in GitHub Desktop.
A sample c++ header file that demonstrates the basic syntax of the Doxygen documentation.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
/** | |
* @file SampleDoxygenAnnotations.h | |
* @author My Self | |
* @date 9 Sep 2016 | |
* @brief File containing examples of doxygen usage for quick reference. | |
* | |
* Here typically goes a more extensive explanation of what the header | |
* defines. Doxygens tags are words preceeded by either a backslash @\ | |
* or by an at symbol @@. | |
* @see http://www.stack.nl/~dimitri/doxygen/docblocks.html | |
* @see http://www.stack.nl/~dimitri/doxygen/commands.html | |
*/ | |
# ifndef _SAMPLE_DOXYGEN_ANNOTATIONS_H | |
# define _SAMPLE_DOXYGEN_ANNOTATIONS_H | |
# include <stdio.h> | |
# include <math.h> | |
# include "local_header.h" | |
/** | |
* @brief a macro that marks the functions that will be exported. | |
*/ | |
#define EXPORT | |
/** | |
* @brief Use brief, otherwise the index won't have a brief explanation. | |
* | |
* Detailed explanation for an enum type. | |
*/ | |
typedef enum Enum_enum { | |
ENUM_FIRST, /**< Some documentation for first. */ | |
ENUM_SECOND, /**< Some documentation for second. */ | |
/** | |
* Some documentations for Etc. | |
*/ | |
ENUM_ETC | |
} SampleEnum; | |
/** | |
* @brief Use brief, otherwise the index won't have a brief explanation. | |
* | |
* Detailed explanation. | |
* | |
* @deprecated Starts a paragraph indicating that this documentation block | |
* belongs to a deprecated entity. Can be used to describe alternatives, | |
* expected life span, etc. | |
*/ | |
typedef struct SampleStruct_struct { | |
int a; /**< Some documentation for the member SampleStruct#a. */ | |
int b; /**< Some documentation for the member SampleStruct#b. */ | |
/** | |
* Some documentation for SampleStruct#c. | |
*/ | |
double c; | |
} SampleStruct; | |
/** | |
* @brief Example showing how to document a function with Doxygen. | |
* | |
* Description of what the function does. This part may refer to the parameters | |
* of the function, like @p param1 or @p param2. A word of code can also be | |
* inserted like @c this which is equivalent to <tt>this</tt> and can be useful | |
* to say that the function returns a @c void or an @c int. If you want to have | |
* more than one word in typewriter font, then just use @<tt@>. | |
* We can also include text verbatim, | |
* @verbatim like this@endverbatim | |
* Sometimes it is also convenient to include an example of usage: | |
* @code | |
* SampleStruct *out = Sample_The_Function_Name(param1, param2); | |
* printf("something...\n"); | |
* @endcode | |
* Or, | |
* @code{.py} | |
* pyval = python_func(arg1, arg2) | |
* print pyval | |
* @endcode | |
* when the language is not the one used in the current source file (but | |
* <b>be careful</b> as this may be supported only by recent versions | |
* of Doxygen). By the way, <b>this is how you write bold text</b> or, | |
* if it is just one word, then you can just do @b this. | |
* @param param1 Description of the first parameter of the function. | |
* @param param2 The second one, which follows @p param1. | |
* @return Describe what the function returns. | |
* @see The_Second_Function | |
* @see The_Last_One | |
* @see http://samplesite.sm/ | |
* @note Something to note. | |
* @warning Warning. | |
*/ | |
EXPORT SampleStruct * | |
The_Function_Name(ParamType1 param1, ParamType2 param2 /*, ...*/); | |
/** | |
* @brief A simple stub function to show how links do work. | |
* | |
* Links are generated automatically for webpages (like http://www.google.com) | |
* and for structures, like SampleStruct_struct. For typedef-ed types use | |
* #SampleStruct. | |
* For functions, automatic links are generated when the parenthesis () follow | |
* the name of the function, like The_Function_Name(). | |
* Alternatively, you can use #The_Function_Name. | |
* @return @c NULL is always returned. | |
*/ | |
EXPORT void * | |
The_Second_Function(void); | |
/** | |
* @brief A simple stub function to show how to create bullets and numbered lists. | |
* By putting a number of column-aligned minus (-) signs at the start of a line, | |
* a bullet list will automatically be generated. Instead of the minus sign also | |
* plus (+) or asterisk (*) can be used. Numbered lists can also be generated by | |
* using a minus followed by a hash or by using a number followed by a dot. | |
* Nesting of lists is allowed and is based on indentation of the items. | |
* A list of events: | |
* - mouse events | |
* -# mouse move event | |
* -# mouse click event\n | |
* More info about the click event. | |
* -# mouse double click event | |
* - keyboard events | |
* 1. key down event | |
* 2. key up event | |
* | |
* More text here. | |
*/ | |
EXPORT void * The_Event_Function(void); | |
/** | |
* Brief can be omitted. If you configure Doxygen with | |
* <tt>JAVADOC_AUTOBRIEF=YES</tt>, then the first Line of the comment is used | |
* instead. In this function this would be as if | |
* @verbatim @brief Brief can be omitted. @endverbatim | |
* was used instead. | |
*/ | |
EXPORT void | |
The_Last_One(void); | |
/** | |
* @brief A sample class | |
* | |
* A sample class. A more elaborate class description. Classes are documented mostly the same way that | |
* structures are documented. | |
* A member can be linked like #publicVar. | |
*/ | |
class SampleClass | |
{ | |
public: | |
/** | |
* An enum. | |
* More detailed enum description. | |
*/ | |
enum TEnum { | |
TVal1, /**< enum value TVal1. */ | |
TVal2, /**< enum value TVal2. */ | |
TVal3 /**< enum value TVal3. */ | |
} | |
*enumPtr, /**< enum pointer. Details. */ | |
enumVar; /**< enum variable. Details. */ | |
/** | |
* A constructor. | |
* A more elaborate description of the constructor. | |
*/ | |
SampleClass(); | |
/** | |
* A destructor. | |
* A more elaborate description of the destructor. | |
*/ | |
~SampleClass(); | |
/** | |
* a normal member taking two arguments and returning an integer value. | |
* @param[in] a an integer argument. | |
* @param[in] s a constant character pointer. | |
* @param[out] ret some return value | |
* @see SampleClass() | |
* @see ~SampleClass() | |
* @see testMeToo() | |
* @see publicVar() | |
* @return The test results | |
*/ | |
int testMe(int a,const char *s, int* ret); | |
/** | |
* A pure virtual member. | |
* @see testMe() | |
* @param[in] c1 the first argument. | |
* @param[in] c2 the second argument. | |
* @param[in] buffer Some buffer that returns some data from the function | |
* @param[in, out] bufferSize Gives the length of @paramref buffer to the function and | |
* returns the number of characters written to it upon function termination. | |
*/ | |
virtual void testMeToo(char c1,char c2, char* buffer, int* bufferSize) = 0; | |
/** | |
* a public variable. | |
* Details. | |
*/ | |
int publicVar; | |
/** | |
* a function variable. | |
* Details. | |
*/ | |
int (*handler)(int a,int b); | |
}; | |
#endif /* _SAMPLE_DOXYGEN_ANNOTATIONS_H */ |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
A sample c++ header file that demonstrates the basic syntax of the Doxygen documentation. The file is largely based on the Doxygen usage example (for C) by Matteo Franchin.