Doxygen: Difference between revisions

From FreeCAD Documentation
(→‎Parsing of comments: Renamed section)
Line 30: Line 30:
}}
}}


== Parsing of comments ==
== 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:
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:

Revision as of 03:37, 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.

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&);

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.

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 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

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