C++ code documentation example
doxygen -g ./doc/Doxyfile
- CLI generation of Doxygen documentation
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
- 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 = "..."
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.
///
/// @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
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.
- @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
*/
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
Command Pattern References
- 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
Loading