C++ Document Example 1.2.3
Simple example about how to create C++ project documentation with Doxygen
 
Loading...
Searching...
No Matches
CppDocumentExample

C++ code documentation example

Setup Doxygen

  • Startup command
    doxygen -g ./doc/Doxyfile
  • CLI generation of Doxygen documentation
    doxygen ./doc/Doxyfile

Important Doygen settings

  • Title of the project: PROJECT_NAME = "..."
  • Optional one line description of the project: PROJECT_BRIEF = "..."
  • Disable LaTeX output: GENERATE_LATEX = NO
  • Directory to put the HTML docs OUTPUT_DIRECTORY = ./html/
  • Files and/or directories that contain documented source files: INPUT = ../include ../src
  • Reuse documentation for the group: DISTRIBUTE_GROUP_DOC = YES
  • Show public members of class: EXTRACT_ALL = YES
  • Search subdirectories for input files: RECURSIVE = YES

Diagram generators

  • Dot tool ( Graphviz ) available: HAVE_DOT = YES
  • Use UML notation for class diagrams: UML_LOOK = YES

Useful Doygen settings

General

  • Make a main page out of a markdown: USE_MDFILE_AS_MAINPAGE = "..."
  • Project logo file: PROJECT_LOGO = "..."
  • Match functions declarations and definitions whose arguments contain STL classes: BUILTIN_STL_SUPPORT = YES
  • Exclude documentation from external libraries: EXCLUDE = "..."

Scope related

  • Show private members of class: EXTRACT_PRIVATE = YES
  • Show private virtual members of class: EXTRACT_PRIV_VIRTUAL = YES
  • Show static members of class: EXTRACT_STATIC = YES
  • Show all memebers of internal scope: EXTRACT_PACKAGE = YES
  • Show members of anonymous namespace: EXTRACT_ANON_NSPACES = YES
  • Show used C++ STL containers, smart pointers, etc. : HIDE_UNDOC_RELATIONS = NO

Entrance points

  • Add all the header and source file extensions used: FILE_PATTERNS = *.cpp *.h *.hpp
  • Generate list from all /** @todo */: GENERATE_TODOLIST = YES
  • Generate list from all /** @test */ : GENERATE_TESTLIST = YES
  • Generate list from all /** @bug */ : GENERATE_BUGLIST = YES

Diagram generators

  • Show all members in UML class: UML_LIMIT_NUM_FIELDS = 0
  • Generate a call dependency graph for every global function or class method: CALL_GRAPH = YES
  • Generate a caller dependency graph for every global function or class method: CALLER_GRAPH = YES
  • Show relationship for templates in graphs: TEMPLATE_RELATIONS = YES
  • Hide inheritance and usage relations if the target is undocumented or is not a class: HIDE_UNDOC_RELATIONS = NO
  • Number of threads to use for DOT: DOT_NUM_THREADS = 4

Source browsing

  • Show all functions that reference current function: REFERENCED_BY_RELATION = YES
  • Show all functions referenced by current function: REFERENCES_RELATION = YES
  • Include functions body to the generated HTML's: INLINE_SOURCES = YES
  • Specify files/folders with example code: EXAMPLE_PATH = "..."

Recipe to generate generate call/caller graph

HAVE_DOT = YES
EXTRACT_ALL = YES
EXTRACT_PRIVATE = YES
EXTRACT_STATIC = YES
CALL_GRAPH = YES
CALLER_GRAPH = YES
DISABLE_INDEX = YES
GENERATE_TREEVIEW = YES
RECURSIVE = YES

Consider also:

EXTRACT_PACKAGE = YES
EXTRACT_LOCAL_METHODS = YES
EXTRACT_ANON_NSPACES = YES

Use @includedbygraph , @hideincludedbygraph, @callgraph and @hidecallgraph to control the graph preparation.

Main page recipe

///
/// @mainpage Command Design Pattern Example
/// Main page for the example
///
/// It has to be noted that CMake target still renders the README.md file
/// as main page if it is present in the project - when
/// DOXYGEN_USE_MDFILE_AS_MAINPAGE is set.
///
/// If DOXYGEN_USE_MDFILE_AS_MAINPAGE is set then it is overriden by this
/// section.
///
/// This should be on top of the file or in a separate file.
///
/// @section first_sec_name First section
///
/// Explanation for the first section.
///
/// @section second_sec_name Second section
///
/// Explanation for the second section.
///
/// @subsection second_sub_sec_name Second section's subsection
///
/// Explanation for the second subsection.
///

Useful Doxygen tags

File

  • @file <FILENAME> File Name
  • @author <AUTHOR_NAME> Author name
  • @brief <BRIEF> Short description
  • @date <DATE> Date

General

  • @brief Brief description of class or function (fits a single line)
  • @details Details about class or function
  • @author <AUTHOR NAME> Insert author name

Function Or Method Documentation

  • @param <PARAM> <DESCR> Function or method parameter description
  • @param[in] <PARAM> <DESCR> Input parameter (C-function)
  • @param[out] <PARAM> <DESCR> Output paramter of C-style function that returns multiple values
  • @param[in, out] <PARAM> <DESCR> Parameter used for both input and output in a C-style function.
  • @tparam <PARAM> <DESCR> Template type parameter
  • @throw <EXCEP-DESCR> Specify exceptions that a function can throw
  • @pre <DESCR> Pre conditions
  • @post <DESCR> Post conditions
  • @return <DESCR> Description of return value or type.

Miscellaneous

  • @remark Additional side-notes
  • @note Insert additional note
  • @warning
  • @see SomeClass::Method Reference to some class, method, or web site
  • @li Bullet point
  • @todo <TODO-NOTE> TODO annotation, reminders about what is still needs to be done.

Clang Compiler flags

  • -Wdocumentation-deprecated-sync @deprecated does not match [[deprecated]]
  • -Wdocumentation-html Check HTML syntax
  • -Wdocumentation All of the above
  • -Wdocumentation-unknown-command Warns for unknown Doxygen tags
  • -Wdocumentation-pedantic Strict check of Doxygen syntax + unknown

PlantUML

Install

sudo apt install plantuml

Setup

  • Required: PLANTUML_JAR_PATH
  • Optional: PLANTUML_CFG_FILE, PLANTUML_INCLUDE_PATH

Usage

/**
@startuml
Alice -> Bob : Hello
@enduml
*/

References

Doxygen CMake target

find_package(Doxygen REQUIRED dot)
set(DOXYGEN_PROJECT_NAME "C++ Document Example")
# Other Doxygen options
doxygen_add_docs(docs_target
${PROJECT_SOURCE_DIR}
COMMENT "Generate documentation"
)

Publish with GitHub action

  • Create the github action: .github/workflows/doxygen_publish.yml
  • Go to Settings -> Actions -> General -> Workflow and set Read and write permissions
  • Setup GitHub Pages
  • Go to Settings -> Pages
  • Set Build and deployment to Deploy from a branch
  • Set Branch to gh-pages and /(root)
  • Resulting site is https://vlantonov.github.io/CppDocumentExample/

Publish with Gitlab Pages

Doxygen C++ examples

Command Pattern References

  • plantUML diagram
    • Supported in GitLab
    • Rendered by Doxygen with PlantUML support
    • Not supported in GitHub
  • Mermaid diagram
    • Supported in GitLab
    • Not supported by Doxygen
    • Supported in GitHub
      classDiagram
      class Client
      class Invoker
      class Receiver {
      <<interface>>
      }
      class ContainerReceiver
      class SingleReceiver
      class Command {
      <<interface>>
      }
      class CreateCommand
      class ReadCommand
      class UpdateCommand
      class DeleteCommand
      Command <|.. CreateCommand
      Command <|.. ReadCommand
      Command <|.. UpdateCommand
      Command <|.. DeleteCommand
      Receiver <|.. ContainerReceiver
      Receiver <|.. SingleReceiver
      Client <-- Receiver : Get Response
      Command --> Receiver : Operation params
      Client --> Invoker : Set Command
      Invoker --> Command : Initiate request
  • refactoring.guru:Command
  • Command Design Pattern
  • What Is CRUD (Create, Read, Update, and Delete)?
  • Repository Design Pattern
  • Repository Pattern

Technical References

Example Document pages