Basic Tags
mainpage tag
The main page of a Doxygen documentation is specified using the \mainpage tag. This tag should be placed at the top of the file and should be followed by a brief description of the project. For example:
/**
* \mainpage My Project
*
* This is the main page of the documentation for My Project.
*/Note
If the doxygen generated navigation tree shouldn't have multiple names for index.html, the name used in mainpage tag must be same as the name in Doxygen Project Title.
page tag
You can also use \page command to create a new named page, for example
/**
* \page myPage MyPage
*
* This is a new named page, you can access it by clicking on the link in the navigation tree.
*/file tag
In Doxygen, the \file tag is used to provide documentation for a specific file. The tag should be placed at the top of the file, before any code or other documentation. The basic syntax for the \file tag is:
/**
* \file [file name]
* \brief [brief description of the file]
* [detailed description of the file, including any relevant information about its contents or purpose]
*/
Example
/**
* \file main.c
* \brief Contains the main function for the program
* This file contains the main function for the program, which is responsible for setting up and running the program.
*/You can also use \file command to specify a file that is not included in the project but is related and should be in the documentation.
/**
* \file external.h
* \brief Contains external functions used in the project
* This file contains external functions used in the project and is not included in the project but is related and should be in the documentation.
*/
defgroup tag
In Doxygen, the \defgroup tag is used to group related functions, variables, or other elements together in the documentation. It is used to create a hierarchical structure for the documentation, making it easier to navigate and understand.
The basic syntax for the \defgroup tag is:
/**
* \defgroup group_name group_title
* \brief brief_description
*
* detailed_description
*/
example
/**
* \defgroup math_functions Math Functions
* \brief A collection of mathematical functions
*
* This group contains a variety of mathematical functions, including basic operations like addition and subtraction, as well as more advanced functions like trigonometry and calculus.
*/
Then you can use \ingroup group_name to specify that a function, variable, or other element belongs to a particular group.
/**
* \ingroup math_functions
* \brief Add two numbers
*
* This function adds two numbers and return the result.
*/The \defgroup tags are used to create a hierarchical structure for the documentation, which can be displayed in the navigation tree, making it easier to navigate and understand.
addtogroup
In Doxygen, the \addtogroup tag is used to add a function, variable, or other element to an existing group. It is used in conjunction with the \defgroup tag to create a hierarchical structure for the documentation, making it easier to navigate and understand.
The basic syntax for the \addtogroup tag is:
/**
* \addtogroup group_name
* \{
* [documentation for elements in the group]
* \}
*/For example, suppose we have a group named "math_functions" that has already been defined with the \defgroup tag:
/**
* \defgroup math_functions Math Functions
* \brief A collection of mathematical functions
*
* This group contains a variety of mathematical functions, including basic operations like addition and subtraction, as well as more advanced functions like trigonometry and calculus.
*/We can then use the \addtogroup tag to add a new function to the group:
/**
* \addtogroup math_functions
* \{
* \brief Add two numbers
*
* This function adds two numbers and return the result.
* \}
*/You can also use \ingroup group_name to specify that a function, variable, or other element belongs to a particular group, it has the same effect as \addtogroup
/**
* \ingroup math_functions
* \brief Add two numbers
*
* This function adds two numbers and return the result.
*/Documentation for constants and global variables
Prerequisite: @file tag should be used to parse the file declaring constants and global variables
Putting documentation after members, ie single line comments
single line comments reference
int var; ///< Detailed description after the member
///<Constants
/*!
* \brief constant holding file path of this plugin.
* @details this constant is defined for ease of usage in all classes.\n
This is used in autoloader and for loading template files
*/Global Variables
/**
* @brief Determines wether captcha is enabled in comment form
* @details
It is set in admin panel, in "Captcha Settings"
*/Functions
Use this regexp to get methods
([^\}\r\n\/\$]+)function([^\(\r\n]+)\(anchor tag
Use \anchor tag in doxygen blocks to set named anchors where required. you can refer with the \ref command.
<a name="git_html_pages"></a>
which is equivalent to
\anchor git_html_pages/*! \fn osolAutoLoadRegisterCalled()
* \brief Dummy function to mention **spl_autoload_register(function ($class)** is called.
* After registering this autoload function with SPL, the following line
* would cause the function to attempt to load the \Foo\Bar\Baz\Qux class
* from /path/to/project/src/Baz/Qux.php:
*
* new \Foo\Bar\Baz\Qux;
*
* \param function Function that maps called classes to appropriate source files.
* \exception std::fileNotFound No such file check the spelling of {$class}.
* \return void.
*/Class Documentation
/**
* \class OSOLCCC::Controllers::ContactusController
* \brief \OSOLCCC\Controllers\ContactusController: Used for handling Contact us functionality
* \details
This class is the controller class for contact us module. \n
\par Doxygen Tip
\par instantiation
\OSOLCCC\Controllers\ContactusController::getInstance()\n
* @author
* Name: Sreekanth Dayanand, www.outsource-online.net
* Email: joomla@outsource-online.net
* Url: http://www.outsource-online.net
* ===================================================
* @copyright (C) 2012,2013 Sreekanth Dayanand, Outsource Online (www.outsource-online.net). All rights reserved.
* @license see http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL.
* You can use, redistribute this file and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation.
* If you use this software as a part of own sofware, you must leave copyright notices intact or add OSOLMulticaptcha copyright notices to own.
*
* @date 23rd June 2022
*/Class Methods
/**
* @brief
*
* @param [in] no input parameters
* @return array
* @author Sreekanth Dayanand
* @date 23rd June 2022
* @details
@n
\par Called in
1.
\par Uses Methods
calls
*/Some special tags
Table of Contents
Creates Multilayered ordered List
Warning
This command only works inside related page documentation and not in other documentation blocks and only has effect in the specified output! ie only works on extra pages (@page, @mainpage), not in the regular documentation blocks.
/***********************************//**
* \mainpage Project Title
* \brief example
*
* \tableofcontents
*
* \section sec1 section 1
* blabla
*
* \section sec2 section 2
* blabla
*
* \subsection ssec21 subsection 21
* blabla
***********************************/Another simplified way of creating table of contents using uordered list in any page is here
Special commands for formatting documentation text, named anchor etc.
More Detailed tags example
@mainpage tag
// the above block is for wordpress to detect and assimilate this plugin as part of its system
// below block is for doxygen
/**
@mainpage Captcha and Contact Us Forms for WordPress
Adds OSOLMulticaptcha (http://www.outsource-online.net/osolmulticaptcha-simplest-php-captcha-for-html-forms.html ) to wordpress forms for registration,login,forgot password and comment.
Additionally ,this will enable admin to add contact us form with the same captcha in any wordpress page
just need to insert the code [cccontact] in a page where you want to show contact us form
@par Requirements
PHP GD Library must be available in the server
safe mode must be turned off
The above requirements are default settings in most PHP hosts.however if the captcha isnt showing up you need to check those settings
@date 21st October 2022
@copyright {This project is released under the GNU Public License.}
@author Sreekanth Dayanand
@note short code for this plugin will be 'osolwpccc'. To be used in 'load_plugin_textdomain' and text translation functions. This line is not mandatory but useful for future reference for developers , while modifying the plugin
@par Git Info
(https://github.com/osolgithub/captchaAndContactus4WP/tree/OOP)@n
[documentation](https://osolgithub.github.io/captchaAndContactus4WP/)@n
[documentation repo](https://github.com/osolgithub/captchaAndContactus4WP/tree/gh-pages)@n
*/@file tag Example
/**
* @file custCaptchaContact.php
* @brief Bootstrap file for this plugin.
* @details Starting point of the project.\n
* This file bootstraps the operations of this project\n
* This documentation is shown because *file* tag is used.\n
* This will appear under Main Project >> Files >> File List >> thisFileName \n
\par Hooks Used:
Two Types of WordPress Hooks: <b>Actions</b> and <b>Filters</b>. WordPress includes two types of hooks called Actions and Filters. Actions let you do something at certain predefined points in the WordPress runtime, while Filters let you modify any data processed by WordPress and return it.@n
* @warning without *file* tag, non class files are not documented\n
* Also no global variables will be documented
*
*/@ingroup
/** @file
* @ingroup jsfiles
* @brief this file in jsfiles
*/|
|
|
|