Doxygen: Difference between revisions

From FreeCAD Documentation
(→‎Introduction: The two styles)
(Re-order of information and new section regarding Python)
Line 62: Line 62:
In this case the structural command {{incode|\file}} is used to indicate which source file is being documented; a structural command {{incode|\fn}} indicates that the following code is a function, and the command {{incode|\brief}} is used to give a small description of this function.
In this case the structural command {{incode|\file}} is used to indicate which source file is being documented; a structural command {{incode|\fn}} indicates that the following code is a function, and the command {{incode|\brief}} is used to give a small description of this function.


== Doxygen markup ==
== Parsing of documentation blocks ==


All Doxygen documentation commands start with a backslash {{incode|\}} or an at-sign {{incode|@}}, at your preference. In FreeCAD, C style comments are normally used, that is, a pair of {{incode|/*}} and {{incode|*/}} to delimit the comment. In this case, the {{incode|@}}-sign is used in Doxygen commands to improve readability.
The text inside a special documentation block is parsed before it is written to the HTML and LaTeX output files. During parsing the following steps take place:

* Markdown formatting is replaced by corresponding HTML or special commands.
Some commands can have one or more arguments.
* The special commands inside the documentation are executed. See section [http://www.doxygen.nl/manual/commands.html Special Commands] for an overview of all commands.
* If {{incode|<sharp>}} braces are used the argument is a single word.
* If a line starts with some whitespace followed by one or more asterisks ({{incode|*}}) and then optionally more whitespace, then all whitespace and asterisks are removed.
* If {{incode|(round)}} braces are used the argument extends until the end of the line on which the command was found.
* All resulting blank lines are treated as a paragraph separators. This saves you from placing new-paragraph commands yourself in order to make the generated documentation readable.
* If <code>{curly}</code> braces are used the argument extends until the next paragraph. Paragraphs are delimited by a blank line or by a section indicator.
* Links are created for words corresponding to documented classes. If the word is preceded by a {{incode|%}}-sign, then sign will be removed and the word won't be linked.
* If {{incode|[square]}} brackets are used the argument is optional.
* Links to members are created when certain patterns are found in the text. See section [http://www.doxygen.nl/manual/autolink.html Automatic link generation] for more information.

* HTML tags that are in the documentation are interpreted and converted to \LaTeX equivalents for the \LaTeX output. See section [http://www.doxygen.nl/manual/htmlcmds.html HTML Commands] for an overview of all supported HTML tags.
Some of the most common keywords used in the FreeCAD documentation are
* <code>\addtogroup <name> [(title)]</code>, see [https://www.star.bnl.gov/public/comp/sofi/doxygen/commands.html#cmdaddtogroup \addtogroup]
* <code>\brief { brief description }</code>, see [https://www.star.bnl.gov/public/comp/sofi/doxygen/commands.html#cmdbrief \brief]
* <code>\param <parameter-name> { parameter description }</code>, see [https://www.star.bnl.gov/public/comp/sofi/doxygen/commands.html#cmdparam \param]
* <code>\return { description of the return value }</code>, see [https://www.star.bnl.gov/public/comp/sofi/doxygen/commands.html#cmdreturn \return]
* <code>\note { text }</code>, see [https://www.star.bnl.gov/public/comp/sofi/doxygen/commands.html#cmdnote \note]


== Example with the FreeCAD source code ==
== Example with the FreeCAD source code ==
Line 160: Line 166:
</div>
</div>


== Doxygen markup ==
== Doxygen with Python code ==


Doxygen works best for statically typed languages like C++. However, it can also create documentation for Python files.
All Doxygen documentation commands start with a backslash {{incode|\}} or an at-sign {{incode|@}}, at your preference. In FreeCAD, C style comments are normally used, that is, a pair of {{incode|/*}} and {{incode|*/}} to delimit the comment. In this case, the {{incode|@}}-sign is used in Doxygen commands to improve readability.


There are two ways to comment Python:
Some commands can have one or more arguments.
# The Pythonic way, using docstrings immediately after the class or function definition.
* If {{incode|<sharp>}} braces are used the argument is a single word.
# The Doxygen way, putting comments before the class or function definition.
* If {{incode|(round)}} braces are used the argument extends until the end of the line on which the command was found.
* If <code>{curly}</code> braces are used the argument extends until the next paragraph. Paragraphs are delimited by a blank line or by a section indicator.
* If {{incode|[square]}} brackets are used the argument is optional.


The first option is preferred to comply with PEP8 and most style guidelines for Python. However, in this way Doxygen doesn't recognize special commands.
Some of the most common keywords used in the FreeCAD documentation are

* <code>\addtogroup <name> [(title)]</code>, see [https://www.star.bnl.gov/public/comp/sofi/doxygen/commands.html#cmdaddtogroup \addtogroup]
The second option isn't the traditional Python style, but it allows you to use Doxygen's special commands.
* <code>\brief { brief description }</code>, see [https://www.star.bnl.gov/public/comp/sofi/doxygen/commands.html#cmdbrief \brief]

* <code>\param <parameter-name> { parameter description }</code>, see [https://www.star.bnl.gov/public/comp/sofi/doxygen/commands.html#cmdparam \param]
== Parsing of documentation blocks ==
* <code>\return { description of the return value }</code>, see [https://www.star.bnl.gov/public/comp/sofi/doxygen/commands.html#cmdreturn \return]

* <code>\note { text }</code>, see [https://www.star.bnl.gov/public/comp/sofi/doxygen/commands.html#cmdnote \note]
The text inside a special documentation block is parsed before it is written to the HTML and LaTeX output files. During parsing the following steps take place:
* Markdown formatting is replaced by corresponding HTML or special commands.
* The special commands inside the documentation are executed. See section [http://www.doxygen.nl/manual/commands.html Special Commands] for an overview of all commands.
* If a line starts with some whitespace followed by one or more asterisks ({{incode|*}}) and then optionally more whitespace, then all whitespace and asterisks are removed.
* All resulting blank lines are treated as a paragraph separators. This saves you from placing new-paragraph commands yourself in order to make the generated documentation readable.
* Links are created for words corresponding to documented classes. If the word is preceded by a {{incode|%}}-sign, then sign will be removed and the word won't be linked.
* Links to members are created when certain patterns are found in the text. See section [http://www.doxygen.nl/manual/autolink.html Automatic link generation] for more information.
* HTML tags that are in the documentation are interpreted and converted to \LaTeX equivalents for the \LaTeX output. See section [http://www.doxygen.nl/manual/htmlcmds.html HTML Commands] for an overview of all supported HTML tags.


== FreeCAD doxygen ==
== FreeCAD doxygen ==

Revision as of 04:07, 15 July 2019

Future home of tutorial how to write doxygen for FreeCAD Source_documentation#How_to_integrate_doxygen_in_to_the_FreeCAD_source_code

Doxygen is a very popular tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C#, PHP, Java, and Python. Visit Doxygen website to learn more about the system.

Head to the Manual to start using Doxygen with source files.

Introduction

The Doxygen getting started section mentions some characteristics of documenting the sources.

For members, classes and namespaces there are basically two options:

  1. Place a "special documentation" block in front of the declaration or definition of the member, class or namespace. For file, class and namespace members it is also allowed to place the documentation directly after the member. See section Special comment blocks to learn more about these blocks.
  2. Place a special documentation block somewhere else (another file or another location) and put a "structural command" in the documentation block. A structural command links a documentation block to a certain entity that can be documented (e.g. a member, class, namespace or file). See section Documentation at other places to learn more about structural commands.

Note:

  • The advantage of the first option is that you do not have to repeat the name of the entity (member, class, or namespace), as Doxygen will analyze the code and extract the relevant information.
  • Files can only be documented using the second option, since there is no way to put a documentation block before a file. Of course, file members (functions, variables, typedefs, defines) do not need an explicit structural command; just putting a special documentation block before or after them will work fine.

First style: before the code

Usually you'd want to document the code in the header file, just before the class declaration or function prototype. This keeps the declaration and documentation close to each other, so it's easy to update the latter one if the first one changes.

The special documentation block starts like a C-style comment /* but has an additional asterisk, so /**. The block ends with a matching */.

/**
 * Returns the name of the workbench object.
 */
std::string name() const;

/**
 * Set the name to the workbench object.
 */
void setName(const std::string&);

Second style: everywhere else

Alternatively, the documentation can be placed in another file (or in the same file at the top or bottom, wherever), away from the class declaration or function prototype. In this case, you may have duplicated information, once in the actual header file, and a twice in the documentation file.

First file, source.h:

std::string name() const;
void setName(const std::string&);

Second file, source.h.dox:

/** \file source.h
 *  \brief The documentation of source.h
 *   
 *   The details of this file go here.
 */

/** \fn std::string name() const;
 *  \brief Returns the name of the workbench object.
 */
/** \fn void setName(const std::string&);
 *  \brief Set the name to the workbench object.
 */

In this case the structural command \file is used to indicate which source file is being documented; a structural command \fn indicates that the following code is a function, and the command \brief is used to give a small description of this function.

Doxygen markup

All Doxygen documentation commands start with a backslash \ or an at-sign @, at your preference. In FreeCAD, C style comments are normally used, that is, a pair of /* and */ to delimit the comment. In this case, the @-sign is used in Doxygen commands to improve readability.

Some commands can have one or more arguments.

  • If <sharp> braces are used the argument is a single word.
  • If (round) braces are used the argument extends until the end of the line on which the command was found.
  • If {curly} braces are used the argument extends until the next paragraph. Paragraphs are delimited by a blank line or by a section indicator.
  • If [square] brackets are used the argument is optional.

Some of the most common keywords used in the FreeCAD documentation are

  • \addtogroup <name> [(title)], see \addtogroup
  • \brief { brief description }, see \brief
  • \param <parameter-name> { parameter description }, see \param
  • \return { description of the return value }, see \return
  • \note { text }, see \note

Example with the FreeCAD source code

The code in the file src/Gui/Workbench.h defines the Gui::Workbench class.

Example code from src/Gui/Workbench.h

/**
 * This is the base class for the workbench facility. Each FreeCAD module can provide its own 
 * workbench implementation. The workbench defines which GUI elements (such as toolbars, menus, 
 * dockable windows, ...) are added to the mainwindow and which gets removed or hidden. 
 * When a workbench object gets activated the first time the module - it stands for - gets 
 * loaded into RAM.
 * @author Werner Mayer
 */
class GuiExport Workbench : public Base::BaseClass
{
    TYPESYSTEM_HEADER();

public:
    /** Constructs a workbench object. */
    Workbench();
    virtual ~Workbench();
    /**
     * Returns the name of the workbench object.
     */
    std::string name() const;
    /**
     * Set the name to the workbench object.
     */
    void setName(const std::string&);
    /**
     * The default implementation returns an instance of @ref WorkbenchPy.
     */
    PyObject* getPyObject();
    /** Sets up the contextmenu for this workbench. 
     * The default implementation does nothing.
     */
    virtual void setupContextMenu(const char* recipient,MenuItem*) const;
    /** Sets up the contextmenu for the main window for this workbench. 
     * The default implementation does nothing.
     */
    virtual void createMainWindowPopupMenu(MenuItem*) const;
    /** 
     * Activates the workbench and adds/removes GUI elements.
     */
    bool activate();
    /**
     * Translates the window titles of all menus, toolbars and dock windows.
     */
    void retranslate() const;
    /** Run some actions when the workbench gets activated. */
    virtual void activated();
    /** Run some actions when the workbench gets deactivated. */
    virtual void deactivated();

    /// helper to add TaskWatcher to the TaskView
    void addTaskWatcher(const std::vector<Gui::TaskView::TaskWatcher*> &Watcher);
    /// remove the added TaskWatcher
    void removeTaskWatcher(void);

protected:
    /** Returns a MenuItem tree structure of menus for this workbench. */
    virtual MenuItem* setupMenuBar() const=0;
    /** Returns a ToolBarItem tree structure of toolbars for this workbench. */
    virtual ToolBarItem* setupToolBars() const=0;
    /** Returns a ToolBarItem tree structure of command bars for this workbench. */
    virtual ToolBarItem* setupCommandBars() const=0;
    /** Returns a DockWindowItems structure of dock windows this workbench. */
    virtual DockWindowItems* setupDockWindows() const=0;

private:
    /**
     * The method imports the user defined toolbars or toolbox bars and creates
     * a ToolBarItem tree structure.
     */
    void setupCustomToolbars(ToolBarItem* root, const char* toolbar) const;
    void setupCustomToolbars(ToolBarItem* root, const Base::Reference<ParameterGrp>& hGrp) const;
    void setupCustomShortcuts() const;

private:
    std::string _name;
};

Doxygen with Python code

Doxygen works best for statically typed languages like C++. However, it can also create documentation for Python files.

There are two ways to comment Python:

  1. The Pythonic way, using docstrings immediately after the class or function definition.
  2. The Doxygen way, putting comments before the class or function definition.

The first option is preferred to comply with PEP8 and most style guidelines for Python. However, in this way Doxygen doesn't recognize special commands.

The second option isn't the traditional Python style, but it allows you to use Doxygen's special commands.

Parsing of documentation blocks

The text inside a special documentation block is parsed before it is written to the HTML and LaTeX output files. During parsing the following steps take place:

  • Markdown formatting is replaced by corresponding HTML or special commands.
  • The special commands inside the documentation are executed. See section Special Commands for an overview of all commands.
  • If a line starts with some whitespace followed by one or more asterisks (*) and then optionally more whitespace, then all whitespace and asterisks are removed.
  • All resulting blank lines are treated as a paragraph separators. This saves you from placing new-paragraph commands yourself in order to make the generated documentation readable.
  • Links are created for words corresponding to documented classes. If the word is preceded by a %-sign, then sign will be removed and the word won't be linked.
  • Links to members are created when certain patterns are found in the text. See section Automatic link generation for more information.
  • HTML tags that are in the documentation are interpreted and converted to \LaTeX equivalents for the \LaTeX output. See section HTML Commands for an overview of all supported HTML tags.

FreeCAD doxygen

FC doxygen formatting

The FC project has chosen the following method for it's doxygen comment blocks: As it's special char of choice

  • \note ex. \note added in FreeCAD 0.17

Note: Please also read: https://github.com/FreeCAD/FreeCAD/blob/master/src/Doc/doctips.dox