C++ code documentation example

• Startup command

doxygen -g ./doc/Doxyfile

• CLI generation of Doxygen documentation

doxygen ./doc/Doxyfile

• 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

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

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

• 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

• 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

• 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

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

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.

///
/// @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.
///

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

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

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

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

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

sudo apt install plantuml

• Required: PLANTUML_JAR_PATH
• Optional: PLANTUML_CFG_FILE, PLANTUML_INCLUDE_PATH

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

• PlantUML
• PlantUML : Doxygen
• Doxygen : PlantUML
• CMake FindPlantUML
• Adding UML Diagrams to Doxygen documentation
• Creating C4 and UML Diagrams Using PlantUML with VSCode Extension
• https://github.com/jitsuCM/doxygraph
• Clang Wdocumentation
• Clang Compiler User’s Manual: Comment Parsing Options

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

• Documentation can be created without compiling the project: make docs_target
• FindDoxygen
• Quick setup to use Doxygen with CMake
• Build doxygen from CMake script

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

• Follow the steps in GitLab Pages
• Setup the pipeline in .gitlab-ci.yml as shown here
• Go to Deploy > Pages section and untick the Use unique domain
• Go to Settings > General > Visibility and select Everyone in pages section.
• Resulting site is https://vladiant.gitlab.io/CppDocumentExample/

• How to configure Doxygen for C++ code
• Creating a visualization of a C++ project with doxygen
• Learn how to use doxygen
• CPP / C++ Notes - Doxygen - Documentation Generator
• Doxygen for C++ projects
• Doxygen with Graphviz to generate call graph on Mac
• Doxygen C++ documentation for complete beginners

• plantUML diagram
  • Supported in GitLab
  • Rendered by Doxygen with PlantUML support
  • Not supported in GitHub

component Client
component Invoker

interface Receiver
component ContainerReceiver
component SingleReceiver

interface Command
component CreateCommand
component ReadCommand
component UpdateCommand
component DeleteCommand

Command <|.up. CreateCommand
Command <|.up. ReadCommand
Command <|.up. UpdateCommand
Command <|.up. DeleteCommand

Receiver <|.down. ContainerReceiver
Receiver <|.down. SingleReceiver

Client <- Receiver : Get Response
Command -down-> Receiver : Operation params
Client -up-> Invoker : Set Command
Invoker -> Command : Initiate request

• 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

• The Copy-and-Swap Idiom
• What std::exchange does, and how to remember it
• std::exchange Patterns: Fast, Safe, Expressive, and Probably Underused

• https://github.com/nullromo/doxygen-example
• https://gitlab.com/pages/doxygen
• Projects using doxygen