Doxygen (How to?)

From kalashnikovdb
Jump to: navigation, search

Doxygen for python

System requirements and creating documentation

  • Install doxygen (sudo apt-get install doxygen)
  • Download the latest version of doxypy
  • Generate a configuration file (doxygen -g config.dox)
  • Edit the file config.dox:
  PROJECT_NAME = #Your Project Name would go here
  PROJECT_NUMBER = #Your version/revision number goes here
  OUTPUT_DIRECTORY = #Where you want the documentation going
  FILE_PATTERNS = *.py
  RECURSIVE = YES
  INPUT_FILTER = "python /path/to/doxypy.py" #set this to where you extracted doxypy
  FILTER_SOURCE_FILES = YES
  INPUT = #where the source files are
  run the "doxygen config.dox" from the project root folder 

Comments

  • For Python there is a standard way of documenting the code using so called documentation strings. For comments use the next example of file setup.py:
  """
  @file setup.py Added SWIG interface
  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.
   
  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU Library General Public License for more details.
    
  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 51 Franklin Street, Fifth Floor Boston, MA 02110-1301,  USA
  """
from distutils.core import setup, Extension
""" @author Krunoslav Đuras @brief Description """
kalashnikovDB_module = Extension ('_kalashnikovDB', sources=['kalashnikovDB_wrap.c' \], ) setup (name = 'kalashnikovDB', description = """kalashnikovDB database system""", ext_modules = [kalashnikovDB_module], py_modules = ["kalashnikovDB"], )
  • As we see, this example contains """ at start of comment and on the end (also, ## can be used in the start and the end, but the lines between start with #).


Special commands like \author, \details etc. are also supported in doxygen, and start with sign \ or with @.

Here is the another example of HTML documentation that is generated by doxygen.

More about special commands: Link

Doxygen for C

System requirements and creating documentation

  • Install doxygen (sudo apt-get install doxygen)
  • Generate a configuration file (doxygen -g config.dox)
  • Edit the file config.dox:
  PROJECT_NAME = #Your Project Name would go here
  PROJECT_NUMBER = #Your version/revision number goes here
  OUTPUT_DIRECTORY = #Where you want the documentation going
  FILE_PATTERNS = *.c
  RECURSIVE = YES
  FILTER_SOURCE_FILES = YES
  INPUT = #where the source files are
  run the "doxygen config.dox" from the project root folder 

Comments

  • Here we have different way to comment code. There are several ways to mark a comment block as a detailed description.
  • Special code for comments are same in python like in C language.
  • Next example shows the correct comment of file debug.c:
  /**
  @file debug.c Provides functions for debuging
  */
  /*
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version.
  * 
  * This program is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU Library General Public License for more details.
  * 
  * You should have received a copy of the GNU General Public License
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 51 Franklin Street, Fifth Floor Boston, MA 02110-1301,  USA
  */

  #include "debug.h"
/** * @author Dino Laktašić * @brief Function for printing debug message. * @param level level of debug information for a given DB module * @param type the name of DB module for which to print debug information * @param format format for the output message * @param ... variable number of (different) type args used in printf * @return if debug message is printed return 1, else return 0 */
int Ak_dbg_messg(DEBUG_LEVEL level, DEBUG_TYPE type, const char *format, ...) { /*if (DEBUG_NONE) { return 0; }*/
if ((level == 0 || type == 0 || format == NULL) && !DEBUG_ALL) { return 0; }
va_list args; va_start(args, format); vprintf(format, args); va_end(args); return 1; }

Here is the another example of HTML documentation that is generated by doxygen.

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox