Doxygen: Difference between revisions

From FreeCAD Documentation
(→‎Background: Fixed the links to the Doxygen documentation)
(→‎Background: Information on parsing)
Line 4: Line 4:
Visit the [https://www.star.bnl.gov/public/comp/sofi/doxygen/starting.html starting documentation] to learn the first steps in using Doxygen with source files.
Visit the [https://www.star.bnl.gov/public/comp/sofi/doxygen/starting.html starting documentation] to learn the first steps in using Doxygen with source files.


== Background ==
== Introduction ==
From the Doxygen starting documentation, [https://www.star.bnl.gov/public/comp/sofi/doxygen/starting.html Step 3: Documenting the sources].
From the Doxygen starting documentation, [https://www.star.bnl.gov/public/comp/sofi/doxygen/starting.html Step 3: Documenting the sources].


Line 14: Line 14:
*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.
*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 in front or behind them will work fine.
*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 in front or behind them will work fine.

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 special commands inside the documentation are executed. See section [https://www.star.bnl.gov/public/comp/sofi/doxygen/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.
* Links to members are created when certain patterns are found in the text. See section [https://www.star.bnl.gov/public/comp/sofi/doxygen/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 [https://www.star.bnl.gov/public/comp/sofi/doxygen/htmlcmds.html HTML Commands] for an overview of all supported HTML tags.


== Explanation of doxygen markup ==
== Explanation of doxygen markup ==

Revision as of 21:21, 13 July 2019

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

Visit the starting documentation to learn the first steps in using Doxygen with source files.

Introduction

From the Doxygen starting documentation, Step 3: 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 special documentation 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 in front or behind them will work fine.

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

Explanation of doxygen markup

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

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