The page you’re looking for does not exist. It may have been moved. You can return to the start page, or follow one of the links in the navigation to the left.
+If you arrived on this page by clicking on a link, please notify the owner of the site that the link is broken. +If you typed the URL of this page manually, please double check that you entered the address correctly.
+The page you requested has been relocated to https://www.mrdocs.com/mrdocs/develop/index.html.
diff --git a/docs/mrdocs/develop/_attachments/mrdocs.schema.json b/docs/mrdocs/develop/_attachments/mrdocs.schema.json new file mode 100644 index 000000000..b77be7d54 --- /dev/null +++ b/docs/mrdocs/develop/_attachments/mrdocs.schema.json @@ -0,0 +1,252 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "properties": { + "addons": { + "default": "The code should be documented with the Doc Comment format, also informally known as "javadoc" format or Doxygen-style comments.
+In its most basic form, these are usually comment blocks between /** and */ placed above a class, function, or field declaration:
/** The main information about a person
+
+ This class represents a person with
+ a name and an age. This is the
+ information about a person that
+ we need to store in our system.
+ */
+struct person
+{
+ std::string name;
+ int age;
+}
+
+/** A function to greet a person
+
+ This function takes a person and
+ prints a greeting message.
+
+ @param p The person to greet
+ */
+void greet(person const& p);A common alternative is to use ///, especially for single-line comments:
/// A constant representing the number of hours in a day
+static constexpr int hours_in_day = 24;Both the class and the function above have doc comments with a brief sentence and a detailed description.
+Most doc comments will contain these two sections, which could also be explicitly marked with @brief and @details commands.
Doc comments can also contain a number of special commands such as @param that are used to document the parameters of a function.
The following commands can be used to format the text in the doc comments:
+Command |
+Description |
+
|
+Formats the text in italics |
+
|
+Formats the text in italics |
+
|
+Formats the text in italics |
+
|
+Formats the text in bold |
+
|
+Formats the text in bold |
+
MrDocs uses a configuration file to control how the documentation is generated. +The file is used to specify options such as the generator to use, additional compilation options, and filters.
+Here’s an example of a configuration file:
+source-root: ../include
+multipage: false
+generate: adocTo get linting and autocompletion in the config file, a schema for the config can be specified.
+In JetBrains IDEs, # $schema: <url> can be used to bind a schema to a file.
+In editors with plugins based on the YAML language server, # yaml-language-server: $schema=<url> can be used.
+The schema for mrdocs.yml is provided here.
+The following shows an example of a file specifying an inline-schema that’s compatible with JetBrains IDEs and editors using the YAML language server.
# $schema: https://mrdocs.com/docs/mrdocs/develop/_attachments/mrdocs.schema.json
+# yaml-language-server: $schema=https://mrdocs.com/docs/mrdocs/develop/_attachments/mrdocs.schema.json
+
+source-root: ../include
+multipage: false
+generate: adocA number of options can be used to specify with which compile options MrDocs should be run.
+source-root: ..
+compilation-database: ../CMakeLists.txt
+cmake: '-D MRDOCS_BUILD=ON'
+defines: 'MRDOCS_BUILD'The compile options primarily come from the compilation-database file.
+When this file is generated from a CMakeLists.txt script, the cmake option can be used to specify additional options to pass to CMake.
Additionally, the defines option can be used to specify preprocessor definitions that should be used when generating the documentation.
+These definitions are included in all targets of the compilation database.
MrDocs supports multiple output formats that can be specified via the generate option:
| Format | +Description | +
|---|---|
|
+AsciiDoc format. |
+
|
+HTML format. |
+
|
+XML format. |
+
Asciidoc is a text-based format that is easy to read and write. +It can also be converted to other formats such as HTML and Markdown.
+HTML can be generated directly with the html format.
XML is a structured format that can be used in tests or as an intermediary format for other tools.
+The generate option can be used to specify the output format:
# ...
+generate: adoc
+# ...MrDocs attempts to support various alternatives for customizing the output format and style without complex workflows to post-process XML output. +For the Asciidoc and HTML generators, the desired customization can usually be achieved by modifying the templates used to generate the output.
+In the root of the installation directory, you will find the share/mrdocs/addons/generator directory.
+This directory contains the templates used to generate the documentation with the markup formats.
+Users can create a copy of these files and provide their own addons directory via the addons option.
+This allows users to customize the output format to their needs.
addons: /path/to/custom/addonsOne advantage of custom templates over post-processing XML files is the ability to access symbols as a graph.
+If symbol A refers to symbol B, some properties of symbol B are likely to be required in the documentation of A.
+All templates and generators can access a reference to B by searching the symbol tree or simply by accessing the elements A refers to.
Not all symbols in a project may be relevant to the documentation. +MrDocs provides a way to filter out symbols based on their names.
+filters:
+ symbols: (1)
+ exclude: (2)
+ include: (3)| 1 | +Optional symbols key |
+
| 2 | +Optional exclude key |
+
| 3 | +Optional include key |
+
Symbol filter patterns are specified using (optionally) qualified names, and may contain wildcards:
+filters:
+ symbols:
+ exclude:
+ - 'A::B'
+ - 'A::f*'If a symbol matches a pattern in the exclude list, that symbol and its members will not be extracted:
+filters:
+ symbols:
+ exclude:
+ - 'A'// ok, does not match any excluded pattern
+void f0();
+
+namespace A // matches the pattern 'A', will not be extracted
+{
+ // enclosing namespace matches an excluded pattern:
+ // the symbol will not be extracted
+ void f1();
+}The filters.symbols.include key can be used to override the exclude list for specific symbols.
+A symbol which matches an included pattern and an excluded pattern will be extracted.
This permits fine-grained control of extraction for individual members of a class or namespace:
+filters:
+ symbols:
+ exclude:
+ - 'A'
+ include:
+ - 'A::g*'namespace A
+{
+ // enclosing namespace matches an excluded pattern, will not be extracted
+ void f0();
+
+ // ok, matches the pattern 'A::g*' which overrides the exclude list
+ void g0();
+}In order for a filter pattern to match a symbol, it must consist of simple identifiers that match the name as written in its declaration: namespace aliases, typedef-names, and decltype specifiers naming the symbol cannot be used.
| + + | ++Specifying include patterns is only useful when the pattern would match a subset of symbols matched by an exclude pattern. +An include pattern without a subsuming exclude pattern will be ignored. + | +
Symbols can also be filtered based on the files they are declared in. +This can be useful for excluding files that exclusively contain implementation details or test code.
+input:
+ include:
+ - ../include (1)
+ file-patterns:
+ - *.hpp (2)| 1 | +A list of directories to include. +Only symbols defined in these files will be extracted. | +
| 2 | +A list of file patterns to include. +Only symbols defined in files matching these patterns will be extracted. | +
The implementation-detail and see-below options can be used to designate namespaces as implementation detail namespaces.
implementation-detail: 'impl'
+see-below: 'see_below'If a namespace is designated as an implementation detail namespace, all symbols within that namespace will be marked as implementation details in the documentation.
+namespace impl
+{
+ class A {};
+}
+
+/// @brief A foo function
+A foo();The impl namespace is designated as an implementation detail namespace, so all symbols within it will be marked as implementation details in the documentation.
+This means the symbol A would not be documented and the function foo could be documented as follows:
/* implementation detail */ foo();On the other hand, if a namespace is designated as a see_below namespace, all symbols within that namespace will be marked as "see below" in the documentation.
namespace see_below
+{
+ class B {};
+}In the documentation, the symbol B would be marked as "see-below" and could be documented as:
class B { /* see below */ };The following options can be defined both in the configuration file and on the command line, where the command line options always take precedence.
+Options that can only be provided via the command line
The following options can be used to control the general behavior of MrDocs and can only be provided via the command line. These include options to specify inputs and the configuration file, which cannot be set on the configuration file itself.
| Name | +Description | +Default | +
|---|---|---|
+inputs
++(list of paths) + +(Command line only) + |
+Configuration or compilation database files | +[] | +
+config
++(file path) + +(Required, Command line only) + |
+MrDocs configuration file | +"<cwd>/mrdocs.yml" | +
inputs
Configuration or compilation database files
The inputs are configuration files or compilation database files that used to generate the documentation. When the input ends with mrdocs.yml, it is interpreted as a configuration file, the file is read and the options are used to generate the documentation as if it was provided to the config option. When the input ends with compilation_database.json or CMakeLists.txt, it is interpreted as a compilation database file, the file is read and the compiler flags are used to generate the documentation as if it was provided to the compilation-database option.
+
config
MrDocs configuration file
The configuration file is a YAML file that contains the options used to generate the documentation. The configuration file is read and the options are used to generate the documentation. The configuration file can be used to specify the source code, the output directory, the compilation database, the generator, and the filters.
+
Paths to the source code and output directories
| Name | +Description | +Default | +
|---|---|---|
+source-root
++(directory path) + |
+Path to the root directory of the source code | +"<config-dir>" | +
+output
++(path) + |
+Directory or file for generating output | +"<config-dir>/reference-output" | +
+compilation-database
++(file path) + |
+Path to the compilation database | ++ |
source-root
Path to the root directory of the source code
+
output
Directory or file for generating output
Multipage generators expect a directory. Single page generators expect a file or a directory where the file will be created. If the directory does not exist, it will be created.
+
compilation-database
Path to the compilation database
Path to the compilation database or a build script to generate it. The compilation database is a JSON file that contains the compiler commands used to build the source code. The compilation database is used to extract the compiler flags and the source files used to build the source code and extract symbols. This option also accepts the path to a build script such as CMakeLists.txt to be used to generate the compilation database. In this case, MrDocs will look for CMake in PATH or in CMAKE_ROOT and run the script to generate the compilation database file.
+
Options for building the source code
When MrDocs is responsible to running the build scripts and generating the compilation database, these options are used to build the source code.
| Name | +Description | +Default | +
|---|---|---|
+cmake
++(string) + |
+CMake arguments when generating the compilation database from CMakeLists.txt | ++ |
+defines
++(list of strings) + |
+Additional defines passed to the compiler | +[] | +
+use-system-stdlib
++(boolean) + |
+Use the system standard library | +false | +
+stdlib-includes
++(list of paths) + |
+Standard Library include paths | +["<mrdocs-root>/share/mrdocs/libcxx", "<mrdocs-root>/share/mrdocs/clang"] | +
+system-includes
++(list of paths) + |
+System include paths | +[] | +
+includes
++(list of paths) + |
+Include paths | +[] | +
cmake
CMake arguments when generating the compilation database from CMakeLists.txt
When the compilation-database option is a CMakeLists.txt file, these arguments are passed to the cmake command to generate the compilation_database.json.
+
defines
Additional defines passed to the compiler
Additional defines passed to the compiler when building the source code. These defines are added to the compilation database regardless of the strategy to generate it.
+
use-system-stdlib
Use the system standard library
True if the compiler has to use just the system standard library. When set to true, the compiler uses the system standard library instead of the standard library provided by the compiler.
+
stdlib-includes
Standard Library include paths
Standard Library include paths. These paths are used to replace the standard library paths provided by the compiler.
+
system-includes
System include paths
System include paths. These paths are used to add directories to the system include search path. The system include search path is used to search for system headers. The system headers are headers that are provided by the system and are not part of the project. The system headers are used to provide the standard library headers and other system headers. The system headers are not part of the project and are not checked for warnings and errors.
+
includes
Include paths
Include paths. These paths are used to add directories to the include search path. The include search path is used to search for headers. The headers are used to provide declarations and definitions of symbols. The headers are part of the project and are checked for warnings and errors.
+
Generators to create the documentation and their options
| Name | +Description | +Default | +
|---|---|---|
+generate
++(enum) + |
+Generator used to create the documentation | +"adoc" | +
+multipage
++(boolean) + |
+Generate a multipage documentation | +true | +
+base-url
++(string) + |
+Base URL for links to source code | ++ |
+addons
++(path) + |
+Path to the Addons directory | +"<mrdocs-root>/share/mrdocs/addons" | +
generate
Generator used to create the documentation
+
multipage
Generate a multipage documentation
Generates a multipage documentation. The output directory must be a directory. This option acts as a hint to the generator to create a multipage documentation. Whether the hint is followed or not depends on the generator.
+
base-url
Base URL for links to source code
Base URL for links to source code. The base URL is used to create links to the source code in the documentation. The base URL is combined with the path to the source file to create the link.
+
addons
Path to the Addons directory
Path to the Addons directory. The Addons directory contains the template files used by generators to create the documentation. When a custom Addons directory is not specified, the default templates are used. The default templates are located at the share/mrdocs/addons directory of the MrDocs installation. Users can create custom templates by copying the default templates to a custom directory and specifying the custom directory using this option.
+
Filters to include or exclude files and symbols from the documentation
| Name | +Description | +Default | +
|---|---|---|
+referenced-declarations
++(enum) + |
+Extraction policy for references to external declarations | +"dependency" | +
+anonymous-namespaces
++(enum) + |
+Extraction policy for anonymous namespaces | +"always" | +
+inaccessible-members
++(enum) + |
+Extraction policy for inaccessible members | +"always" | +
+inaccessible-bases
++(enum) + |
+Extraction policy for inaccessible base classes | +"always" | +
+see-below
++(list of strings) + |
+Namespaces for symbols rendered as "see-below" | +[] | +
+implementation-defined
++(list of strings) + |
+Namespaces for symbols rendered as "implementation-defined" | +[] | +
+input
++(object) + |
+Include files to extract | ++ |
+filters
++(object) + |
+Filters | ++ |
referenced-declarations
Extraction policy for references to external declarations
Determine whether external declarations should be extracted when they are referenced in the source code. When set to always, external declarations are always extracted. When set to dependency, external declarations are extracted only if they are referenced by the source code. When set to never, external declarations are never extracted.
+
anonymous-namespaces
Extraction policy for anonymous namespaces
Determine whether symbols in anonymous namespaces should be extracted. When set to always, symbols in anonymous namespaces are always extracted. When set to dependency, symbols in anonymous namespaces are extracted only if they are referenced by the source code. When set to never, symbols in anonymous namespaces are never extracted.
+
inaccessible-members
Extraction policy for inaccessible members
Determine whether inaccessible members should be extracted. When set to always, inaccessible members are always extracted. When set to dependency, inaccessible members are extracted only if they are referenced by the source code. When set to never, inaccessible members are never extracted.
+
inaccessible-bases
Extraction policy for inaccessible base classes
Determine whether inaccessible base classes should be extracted. When set to always, inaccessible base classes are always extracted. When set to dependency, inaccessible base classes are extracted only if they are referenced by the source code. When set to never, inaccessible base classes are never extracted.
+
see-below
Namespaces for symbols rendered as "see-below"
Namespaces for symbols rendered as "see-below". Symbols in these namespaces are not extracted and are rendered as "see-below" in the documentation. This option is used to exclude symbols from the documentation that are considered part of the private API of the project.
+
implementation-defined
Namespaces for symbols rendered as "implementation-defined"
Namespaces for symbols rendered as "implementation-defined". Symbols in these namespaces are not extracted and are rendered as "implementation-defined" in the documentation. This option is used to exclude symbols from the documentation that are considered part of the private API of the project.
+
input
Include files to extract
Include files to extract. Only the files listed in this option are extracted. The paths are relative to the mrdocs configuration file.
+
filters
Filters
+
input suboptions
| Name | +Description | +Default | +
|---|---|---|
+input.include
++(list of paths) + |
+Input directories to include | +[] | +
+input.file-patterns
++(list of strings) + |
+File patterns to include | +[] | +
input.include
Input directories to include
Input directories to include. Only the files in these directories are extracted. The paths are relative to the mrdocs configuration file.
+
input.file-patterns
File patterns to include
File patterns to include. Only the files that match these patterns are extracted. The patterns are relative to the input directories.
+
filters suboptions
| Name | +Description | +Default | +
|---|---|---|
+filters.symbols
++(object) + |
+Symbol filters | ++ |
filters.symbols
Symbol filters
Symbol filters. Symbols that match these filters are extracted. The filters are applied to the fully qualified name of the symbol.
+
symbols suboptions
| Name | +Description | +Default | +
|---|---|---|
+filters.symbols.include
++(list of strings) + |
+Specifies symbol inclusion patterns | +[] | +
+filters.symbols.exclude
++(list of strings) + |
+Specifies symbol exclusion patterns | +[] | +
filters.symbols.include
Specifies symbol inclusion patterns
Specifies symbol inclusion patterns. Symbols that match these patterns are extracted. The patterns are applied to the fully qualified name of the symbol.
+
filters.symbols.exclude
Specifies symbol exclusion patterns
Specifies symbol exclusion patterns. Symbols that match these patterns are not extracted. The patterns are applied to the fully qualified name of the symbol.
+
Metadata and C++ constructs to extract
| Name | +Description | +Default | +
|---|---|---|
+detect-sfinae
++(boolean) + |
+Detect SFINAE expressions | +true | +
detect-sfinae
Detect SFINAE expressions
When set to true, MrDocs detects SFINAE expressions in the source code and extracts them as part of the documentation. Expressions such as std::enable_if<...> are detected, removed, and documented as a requirement.
+
Miscellaneous options
| Name | +Description | +Default | +
|---|---|---|
+concurrency
++(unsigned integer) + +(Command line only) + |
+Number of threads to use | +0 | +
+verbose
++(boolean) + |
+Verbose output | +false | +
+report
++(unsigned integer) + |
+The minimum reporting level: 0 to 4 | +1 | +
+ignore-map-errors
++(boolean) + |
+Continue if files are not mapped correctly | +false | +
+ignore-failures
++(boolean) + |
+Whether AST visitation failures should not stop the program | +false | +
concurrency
Number of threads to use
The desired level of concurrency: 0 for hardware-suggested.
+
verbose
Verbose output
Verbose output. When set to true, MrDocs outputs additional information during the generation of the documentation.
+
report
The minimum reporting level: 0 to 4
The reporting level determines the amount of information displayed during the generation of the documentation. The levels are: 0 - no output, 1 - errors only, 2 - errors and warnings, 3 - errors, warnings, and information, 4 - errors, warnings, information, and debug information.
+
ignore-map-errors
Continue if files are not mapped correctly
When set to true, MrDocs continues to generate the documentation even if some files are not mapped correctly. Files are not mapped correctly when the source file is not found or the compilation database does not contain the compiler flags for the source file.
+
ignore-failures
Whether AST visitation failures should not stop the program
When set to true, MrDocs continues to generate the documentation even if there are AST visitation failures. AST visitation failures occur when the source code contains constructs that are not supported by MrDocs.
+
This page contains information for contributors to the MrDocs project. +It is intended to provide an overview of the codebase and the process of adding new features.
+The MrDocs codebase is divided into several modules:
+This section provides an overview of each module and how they interact with each other in the MrDocs codebase.
+MrDocs options affect the behavior of the compilation database, how symbols are extracted, and how the documentation is generated. +They are parsed from the command line and configuration file.
+The main entry point of MrDocs is the DoGenerateAction function in src/tool/GenerateAction.cpp.
+It loads the options, creates the compilation database, and runs the extraction and generation steps.
+The options formed from a combination of command line arguments and configuration file settings.
Command line and common options are defined in src/tool/ToolArgs.hpp.
+The ToolArgs class uses the llvm::cl library to define and parse the command line arguments.
Common options are defined in mrdocs/Config.hpp.
+The Config class represents all public options that could be defined in a configuration file.
+It also provides a representation plugins can use to access public options from the command line or configuration file.
The function clang::mrdocs::loadConfig is also provided to parse all public options from a YAML configuration file.
Internally, MrDocs uses the derived clang::mrdocs::ConfigImpl class (src/lib/Lib/ConfigImpl.hpp) to also store the private representation of parsed options, such as filters.
Common options are stored in the Config class, while the ToolArgs class stores common options and the command line options.
+For instance, the config option can only be set from the command line, as it would be illogical to expect the location of the configuration file to be defined in the configuration file itself.
+On the other hand, the output option can be set from both the command line and the configuration file so that the user can define a default output location in the configuration file.
Thus, after the command line and configuration file options are parsed, they are finalized in the DoGenerateAction function by calling ToolArgs::apply, which overrides the configuration file options in Config with the command line options, when applicable.
As a last step, DoGenerateAction converts the public Config settings into a ConfigImpl object, which is used by the rest of the program with the parsed options.
At this stage, the clang frontend is used to parse the source code and generate an AST.
+The AST information is extracted and stored in a Corpus object (mrdocs/Corpus.hpp).
The second step in DoGenerateAction is to create a CompilationDatabase object, so we can extract symbols from its source files.
+There are multiple possible sources for this file according to the configuration options: the file might be read directly from the path specified in the options, or it might be generated by MrDocs from build scripts.
Whatever the source, a derived MrDocsCompilationDatabase object (lib/Lib/MrDocsCompilationDatabase.hpp) is created to represent the compilation database.
+The difference between the original CompilationDatabase and the MrDocsCompilationDatabase is that the latter includes a number of pre-processing steps to filter and transform compilation commands.
For each compilation command:
+Command line arguments are adjusted
+Warnings are supressed
+Additional defines are added
+Implicit include directories are added
+Unrecognized arguments are removed
+Paths are normalized
+Non C++ files are filtered
+MrDocs represents each C++ symbol or construct as an Info node (mrdocs/Metadata/Info.hpp).
+MrDocs currently defines the following Info nodes:
| Name | +Description | +Declaration | +
|---|---|---|
|
+The symbol is a namespace |
+
|
+
|
+The symbol is a record (class or struct) |
+
|
+
|
+The symbol is a function |
+
|
+
|
+The symbol is an enum |
+
|
+
|
+The symbol is a typedef |
+
|
+
|
+The symbol is a variable |
+
|
+
|
+The symbol is a field |
+
|
+
|
+The symbol is a template specialization |
+
|
+
|
+The symbol is a friend declaration |
+
|
+
|
+The symbol is an enumerator |
+
|
+
|
+The symbol is a deduction guide |
+
|
+
|
+The symbol is a namespace alias |
+
|
+
|
+The symbol is a using declaration |
+
|
+
|
+The symbol is a concept |
+
|
+
Info can not only represent direct AST symbols but also C++ constructs that need to be inferred from these symbols.
+Nodes in the first category will typically be created in the initial extraction step, and nodes in the second category will be created in the finalization step.
When defining a new Info type, it is important to consider how this type will be supported in all other modules of the codebase, including the AST visitor, generators, tests, and the documentation.
+The script .github/check_info_nodes_support.sh will attempt to infer whether most of these features have been implemented for each node type.
MrDocs uses Clang to extract Info objects from the C++ AST.
+Clang offers two interfaces to access the C++ AST: the LibClang and LibTooling libraries.
+MrDocs uses the latter, as it provides full control over the AST traversal process at the cost of an unstable API.
In LibTooling, once we have a Compilation Database, we can create a ClangTool object to run the Clang frontend on a set of source files.
clang::tooling::ClangTool Tool(compilationDatabase, sourceFiles);
+newFrontendActionFactory<clang::SyntaxOnlyAction> actionFactory();
+return Tool.run(actionFactory.get());The clang::tooling::ClangTool::run method takes a clang::tooling::ToolAction object that defines how to process the AST.
+The action object that usually comes from a clang::tooling::FrontendActionFactory.
+In the example above, the SyntaxOnlyAction is used to parse the source code and generate the AST without any further processing.
In MrDocs, this process happens in clang::mrdocs::CorpusImpl::build (src/lib/Lib/CorpusImpl.cpp), where we call Tool.run for each object in the database with our custom ASTAction action and ASTActionFactory factory (src/lib/AST/ASTVisitor.cpp).
While ASTAction is the entry point for processing the AST, the real work is done by the ASTVisitor class.
+As the AST is generated, it is traversed by the ASTVisitor class.
The entry point of this class is ASTVisitor::build, which recursively calls ASTVisitor::traverseDecl for the root clang::TranslationUnitDecl node of the translation unit.
+During the AST traversal stage, the complete AST generated by the clang frontend is walked beginning with this root TranslationUnitDecl node.
Each clang node is converted into a mrdocs::Info node, which is then stored with any relevant information in a mrdocs::Corpus object.
It is during this stage that USRs (universal symbol references) are generated and hashed with SHA1 to form the 160 bit SymbolID for an entity.
+Except for built-in types, all entities referenced in the corpus will be traversed and be assigned a SymbolID; including those from the standard library.
+This is necessary to generate the full interface for user-defined types.
After running the AST traversal on all translation units, CorpusImpl::build contains finalization steps for the Corpus object.
+At this point, we process C++ constructs that are not directly represented in the AST.
The first finalization step happens in CorpusImpl::build (src/lib/Lib/CorpusImpl.cpp), where the Info objects from a single translation unit
+are merged into a map containing the merged results from all other TUs.
+The merging step is necessary as there may be multiple identical definitions of the same entity.
+For instance, this represents the case where a function is declared at different points in the code base and might have different attributes or comments.
+At this step, the doc comments are also finalized.
+Each Info object has a pointer to its Javadoc object (mrdocs/Metadata/Javadoc.hpp), which is a representation of the documentation comments.
After AST traversal and Info merging, the result is stored as a map of Info objects indexed by their respective SymbolID.
+A second finalization step is then performed in clang::mrdocs::finalize (src/lib/Metadata/Finalize.cpp), where any references to SymbolID objects that don’t exist are removed.
+This is necessary because the AST traversal will generate references to entities that should be filtered and are not present in the corpus.
At this point, the Corpus object contains representations of all entities in the code base and further semantic C++ constructs that are not directly represented in the AST can be inferred.
Documentation generators may traverse this structure by calling Corpus::traverse with a Corpus::Visitor derived visitor and the SymbolID of the entity to visit (e.g. the global namespace).
Documentation generators are responsible for traversing the corpus and generating documentation in the desired format.
+The API for documentation generators is defined in mrdocs/Generator.hpp.
The MrDocs codebase is organized as follows:
+include/—The main include directoryThis directory contains the public headers for the MrDocs library.
+include/mrdocs/—The core library headers
include/mrdocs/ADT—Data Structures
include/mrdocs/Dom—The Document Object Model for Abstract Trees
include/mrdocs/Metadata—Info nodes and metadata classes
include/mrdocs/Support—Various utility classes
src/—The main source directoryThis directory contains the source code for the MrDocs library and private headers.
+src/lib/—The core library
src/lib/AST/—The AST traversal code
src/lib/Dom/—The Document Object Model for Abstract Trees
src/lib/Gen/—Generators
src/lib/Lib/—The core library classes
src/lib/Metadata/—Info nodes and metadata classes
src/lib/Support/—Various utility classes
src/test/—The test directory
src/test_suite/—The library used for testing
src/tool/—The main program
share/—Shared resourcesThis directory contains shared resources for the documentation generators and utilities for developers.
+Its subdirectories are installed in the share directory of the installation.
share/—Shared resources for the documentation generators
share/cmake/—CMake modules to generate the documentation
share/gdb/—GDB pretty printers
share/mrdocs/—Shared resources for the documentation generators
docs—DocumentationThis directory contains the documentation for the MrDocs project. +The documentation is written in AsciiDoc and can be built using the Antora tool.
+docs/—Documentation configuration files and scripts
docs/modules/—The documentation asciidoc files
docs/extensions—Antora extensions for the documentation
third-party/—Helpers for third-party librariesThis directory contains build scripts and configuration files for third-party libraries.
+third-party/—Third-party libraries
third-party/llvm/—CMake Presets for LLVM
third-party/duktape/—CMake scripts for Duktape
third-party/lua/—A bundled Lua interpreter
The AST visitor and metadata all use forward slashes to represent file pathnames, even on Windows. +This is so the generated reference documentation does not vary based on the platform.
+Errors thrown by the program should always have type Exception.
+Objects of this type are capable of transporting an Error object.
+This is important for the scripting to work; exceptions are used to propagate errors from library code to scripts and back to the invoking code.
+For exceptional cases, these thrown exceptions should be uncaught.
+The tool installs an uncaught exception handler that prints a stack trace and exits the process immediately.
All new features should be accompanied by tests.
+The mrdocs-test target is used to run the test suites.
+This target has its entry point in src/test/TestMain.cpp, which can take two paths:
Golden testing: When input paths are provided to the test executable via the command line, the test suite will run the DoTestAction() that iterates all files in test-files comparing the input source files with the expected XML output files.
Unit testing: When no input paths are provided, all unit tests will be run via unit_test_main(), defined by the our test-suite library in src/test_suite/test_suite.cpp.
The fixtures for golden testing are defined in test-files/golden-tests, where files in each directory have the following format:
mrdocs.yml: Basic configuration options for all files in this directory.
<filename>.cpp: The input source file to extract symbols from.
<filename>.xml: The expected XML output file generated with the XML generator.
<filename>.bad.xml: The test output file generated when the test fails.
<filename>.yml: Extra configuration options for this specific file.
If you find a bug or have a feature request, please open an issue on the MrDocs GitHub repository: https://github.com/cppalliance/mrdocs/issues
+If you would like to contribute a feature or bug fix, please open a pull request on the MrDocs GitHub repository: https://github.com/cppalliance/mrdocs/pulls
+If you would like to discuss a feature or bug fix before opening a pull request, discussing happen in the #mrdocs channel on the Cpplang Slack: https://cpplang.slack.com/
A few examples of reference documentation generated with MrDocs are available in https://mrdocs.com/demos/:
+ci-all-releases
+| + | Multi Page |
+Single Page |
+|
Library |
+Asciidoc |
+Asciidoc |
+XML |
+
| + |
|
+||
develop
+| + | Multi Page |
+Single Page |
+|
Library |
+Asciidoc |
+Asciidoc |
+XML |
+
| + | + | ||
| + |
|
+||
master
+| + | Multi Page |
+Single Page |
+|
Library |
+Asciidoc |
+Asciidoc |
+XML |
+
| + |
|
+||
v0.0.1
+| + | Multi Page |
+Single Page |
+|
Library |
+Asciidoc |
+Asciidoc |
+XML |
+
| + |
|
+||
v0.0.2
+| + | Multi Page |
+Single Page |
+|
Library |
+Asciidoc |
+Asciidoc |
+XML |
+
| + |
|
+||
C++ API design is challenging. +When you write a function signature, or declare a class, it is at that moment when you are likely to have as much information as you will ever have about what it is supposed to do. +The more time passes before you write the documentation, the less likely you are to remember all the details of what motivated the API in the first place.
+In other words, because best and worst engineers are naturally lazy, the temporal adjacency of the C++ declaration to the documentation improves outcomes. +For this reason, having the documentation be as close as possible to the declaration is ideal. +That is, the spatial adjacency of the C++ declaration to the documentation improves outcomes because it facilitates temporal adjacency.
+In summary, the automated extraction of reference documentation from C++ declarations containing attached documentation comments is ideal because:
+Temporally adjacent documentation is more comprehensive
+Spatially adjacent documentation requires less effort to maintain
+And causally connected documentation is more accurate
+From the perspective of engineers, however, the biggest advantage of automated documentation is that it implies a single source of truth for the API at a low cost. +However, C++ codebases are notoriously difficult to document automatically because of constructs where the code needs to diverge from the intended API that represents the contract with the user.
+Tools like Doxygen typically require workarounds and manual intervention via preprocessor macros to get the documentation right. +These workarounds are problematic because they effectively mean that there are two versions of the code: the well-formed and the ill-formed versions. +This subverts the single sources of truth for the code.
+| + | Mr. Docs | +Automatic | +Manual | +No Reference | +
|---|---|---|---|---|
No workarounds |
+✅ |
+❌ |
+✅ |
+❌ |
+
Nice for users |
+✅ |
+✅ |
+✅ |
+❌ |
+
Single Source of Truth |
+✅ |
+❌ |
+❌ |
+❌ |
+
Less Work for Developers |
+✅ |
+❌ |
+❌ |
+✅ |
+
Always up-to-date |
+✅ |
+✅ |
+❌ |
+❌ |
+
By providing no reference to users, they are forced to read header files to understand the API. +This is a problem because header files are not always the best source of truth for the API. +Developers familiar with cppreference.com will know that the documentation there is often more informative than the header files.
+A common alternative is to provide a manual reference to the API. +Developers duplicate the signatures, which requires extra work. +This strategy tends to work well for small libraries and allows the developer to directly express the contract with the user. +However, as the single source of truth is lost, it becomes unmanageable as the codebase grows. +When the declaration changes, they forget to edit the docs, and the reference becomes out of date.
+In this case, it looks like the best solution is to automate the documentation. +The causal connection between the declaration and the generated documentation improves outcomes. +That’s when developers face difficulties with existing tools like Doxygen, which require workarounds and manual intervention to get the documentation right. +The workarounds mean that there are two versions of the code: the well-formed and the ill-formed versions.
+The philosophy behind MrDocs is to provide solutions to these workarounds so that the single source of truth can be maintained with minimal effort by developers. +With Mr.Docs, the documented C++ code should be the same as the code that is compiled.
+Once the documentation is extracted from the code, it is necessary to format it in a way that is useful to the user. +This usually involves generating output files that match the content of the documentation to the user’s needs.
+A limitation of existing tools like Doxygen is that their output formats are not very customizable. +It supports minor customization in the output style and, for custom content formats, it requires much more complex workflows, like generating XML files and writing secondary applications to process them.
+MrDocs attempts to support multiple output formats and customization options. +In practice, MrDocs attempts to provide three levels of customization:
+At the first level, the user can use an existing generator and customize its templates and helper functions.
+The user can write a MrDocs plugin at a second level that defines a new generator.
+At a third level, it can use a generator for a structured file format and consume the output in a more uncomplicated secondary application or script.
+These multiple levels of complexity mean developers can worry only about the documentation content. +In practice, developers rarely need new generators and are usually only interested in changing how an existing generator formats the output. +Removing the necessity of writing and maintaining a secondary application only to customize the output via XML files can save these developers an immense amount of time.
+To deal with the complexity of C++ constructs, MrDocs uses clang’s libtooling API. +That means MrDocs understands all C++: if clang can compile it, MrDocs knows about it.
+Here are a few constructs MrDocs attempts to understand and document automatically from the metadata:
+Overload sets
+Private APIs
+Unspecified Return Types
+Concepts
+Typedef / Aliases
+Constants
+Automatic Related Types
+Macros
+SFINAE
+Hidden Base Classes
+Hidden EBO
+Niebloids
+Coroutines
+
+Automating C++ reference documentation significantly enhances usability by providing a navigable API and ensuring a single, up-to-date source of truth with minimal effort.
+However, documenting C++ poses significant challenges due to discrepancies between the codebase and the public API. Doxygen remains a popular tool, yet it is suboptimal for C++ as it fails to fully comprehend C++ constructs and requires many transformation steps, including the incorporation of many macros within the C++ code. These macros maintain well-formed and ill-formed versions of the code, undermining the goal of unifying the source of truth.
+Existing solutions frequently need better maintenance or usability issues, prompting users to revert to Doxygen.
+An ideal solution would inherently understand C++ constructs, be actively maintained, and offer diverse options for customizing the output format.
+MrDocs embodies these qualities. Supported by full-time developers from the C++ Alliance, MrDocs inherently comprehends C++ constructs without the need for macros and provides various output formats, customizable templates, and plugin support, ensuring it meets the demands of comprehensive and efficient documentation.
+
+Binary packages are available from our Release Page. +Most users should use these packages.
+| + | 🪟 Windows |
+🐧 Linux |
+|||
📃 Release |
+📦 7z |
+📦 msi |
+📦 zip |
+📦 tar.xz |
+📦 tar.gz |
+
|
+ July 10, 2024 |
+
+ (20 MB) |
+
+ (37 MB) |
+
+ (37 MB) |
+
+ (52 MB) |
+
+ (80 MB) |
+
|
+ December 1, 2023 |
+
+ (11 MB) |
+
+ (18 MB) |
+- |
+
+ (19 MB) |
+
+ (28 MB) |
+
|
+ December 1, 2023 |
+
+ (20 MB) |
+
+ (37 MB) |
+
+ (37 MB) |
+
+ (52 MB) |
+
+ (80 MB) |
+
The following instructions assume we are at a parent directory that’s going to contain both the MrDocs and the third-party dependencies directories.
+
+ <parent-directory>
+ + mrdocs
+ + third-partyClone the MrDocs repository with:
+git clone https://github.com/cppalliance/mrdocsAlso create and go to the third-party directory, where we are going to download and install our dependencies:
mkdir third-party
+cd third-party| + + | +
+
+
+These instructions assume all dependencies are installed in the |
+
MrDocs uses the fmt library for formatting strings.
+From the third-party directory, you can clone the fmt repository and install it with the following commands:
git clone https://github.com/fmtlib/fmt --branch 10.2.1 --depth 1 (1)
+cd fmt
+cmake -S . -B ./build -DCMAKE_BUILD_TYPE=Release -D FMT_DOC=OFF -D FMT_TEST=OFF (2)
+cmake --build ./build --config Release (3)
+cmake --install ./build --prefix ./install (4)
+cd ..| 1 | +Shallow clones the fmt repository. | +
| 2 | +Configure the fmt library with CMake, excluding the documentation and tests. | +
| 3 | +Builds the fmt library in the build directory. |
+
| 4 | +Installs the fmt library in the install directory. |
+
| + + | +
+
+
+All instructions in this document assume you are using a CMake version above 3.26. +Binaries are available at CMake’s official website. + |
+
If you prefer using Vcpkg to install dependencies, you can install VcPkg and fmt with the following commands from the third-party directory:
Windows PowerShell
+Unix Variants
+git clone https://github.com/microsoft/vcpkg.git -b master (1)
+cd vcpkg
+bootstrap-vcpkg.bat (2)
+vcpkg.exe install fmt --triplet x64-windows (3)| 1 | +Clones the Vcpkg repository. | +
| 2 | +Bootstraps Vcpkg. | +
| 3 | +Installs the fmt library. |
+
git clone https://github.com/microsoft/vcpkg.git -b master (1)
+cd vcpkg
+./bootstrap-vcpkg.sh (2)
+./vcpkg install fmt (3)| 1 | +Clones the Vcpkg repository. | +
| 2 | +Bootstraps Vcpkg. | +
| 3 | +Installs the fmt library. |
+
| + + | +
+
+
+You can also install
+
+In this mode, VcPkg will create separate installed trees for each project and configuration. +This is the recommended vcpkg mode for most users, according to the vcpkg documentation. + |
+
MrDocs uses the duktape library for JavaScript parsing.
+From the third-party directory, you can download the duktape source code from the official release:
Windows PowerShell
+Unix Variants
+Invoke-WebRequest -Uri "https://github.com/svaarala/duktape/releases/download/v2.7.0/duktape-2.7.0.tar.xz" -OutFile "duktape-2.7.0.tar.xz" (1)| 1 | +Downloads the duktape source code. |
+
curl -LJO https://github.com/svaarala/duktape/releases/download/v2.7.0/duktape-2.7.0.tar.xz (1)| 1 | +Downloads the duktape source code. |
+
Then patch the Duktape source code to provide CMake support.
+tar -xf duktape-2.7.0.tar.xz (1)
+cp ../mrdocs/third-party/duktape/CMakeLists.txt ./duktape-2.7.0/CMakeLists.txt (2)
+cp ../mrdocs/third-party/duktape/duktapeConfig.cmake.in ./duktape-2.7.0/duktapeConfig.cmake.in (3)
+cd duktape-2.7.0| 1 | +Extracts the duktape source code. |
+
| 2 | +Patches the source code with a CMakeLists.txt file to the duktape-2.7.0 directory so that we can build it with CMake. |
+
| 3 | +Copies the duktapeConfig.cmake.in file to the duktape-2.7.0 directory so that we can install it with CMake and find it later from other CMake projects. |
+
Now adjust the duk_config.h file to indicate we are statically building Duktape.
Windows PowerShell
+Unix Variants
+$content = Get-Content -Path "src\duk_config.h" (1)
+$content = $content -replace '#define DUK_F_DLL_BUILD', '#undef DUK_F_DLL_BUILD' (2)
+$content | Set-Content -Path "src\duk_config.h" (3)| 1 | +Read the content of duk_config.h |
+
| 2 | +Replace the DUK_F_DLL_BUILD macro with #undef DUK_F_DLL_BUILD |
+
| 3 | +Write the content back to the file | +
sed -i 's/#define DUK_F_DLL_BUILD/#undef DUK_F_DLL_BUILD/g' "src/duk_config.h" (1)| 1 | +Disables the DUK_F_DLL_BUILD macro in the duk_config.h file to indicate we are statically building duktape. |
+
And finally install the library with CMake:
+cmake -S . -B ./build -DCMAKE_BUILD_TYPE=Release (1)
+cmake --build ./build --config Release (2)
+cmake --install ./build --prefix ./install (3)| 1 | +Configures the duktape library with CMake. |
+
| 2 | +Builds the duktape library in the build directory. |
+
| 3 | +Installs the duktape library with CMake support in the install directory. |
+
The scripts above downloads the duktape source code, extracts it, and configures it with CMake.
+The CMake scripts provided by MrDocs are copied to the duktape-2.7.0 directory to facilitate the build process with CMake and provide CMake installation scripts for other projects.
If you prefer using Vcpkg to install dependencies, you can install duktape with the following commands from the third-party directory:
Windows PowerShell
+Unix Variants
+cd vcpkg
+vcpkg.exe install duktape --triplet x64-windows (1)| 1 | +Installs the duktape library. |
+
cd vcpkg
+./vcpkg install duktape (1)| 1 | +Installs the duktape library. |
+
| + + | +
+These examples assume VcPkg is already installed in the third-party/vcpkg directory (see the Fmt section).
+ |
+
MrDocs uses libxml2 tools for tests.
+Only developers need to install this dependency.
+Users can skip this step.
From the third-party directory, you can clone the libxml2 repository and install it with the following commands:
git clone https://github.com/GNOME/libxml2 --branch v2.12.6 --depth 1 (1)
+cd libxml2
+cmake -S . -B ./build -DCMAKE_BUILD_TYPE=Release -DLIBXML2_WITH_PROGRAMS=ON -DLIBXML2_WITH_FTP=OFF -DLIBXML2_WITH_HTTP=OFF -DLIBXML2_WITH_ICONV=OFF -DLIBXML2_WITH_LEGACY=OFF -DLIBXML2_WITH_LZMA=OFF -DLIBXML2_WITH_ZLIB=OFF -DLIBXML2_WITH_ICU=OFF -DLIBXML2_WITH_TESTS=OFF -DLIBXML2_WITH_HTML=ON -DLIBXML2_WITH_C14N=ON -DLIBXML2_WITH_CATALOG=ON -DLIBXML2_WITH_DEBUG=ON -DLIBXML2_WITH_ISO8859X=ON -DLIBXML2_WITH_MEM_DEBUG=OFF -DLIBXML2_WITH_MODULES=ON -DLIBXML2_WITH_OUTPUT=ON -DLIBXML2_WITH_PATTERN=ON -DLIBXML2_WITH_PUSH=ON -DLIBXML2_WITH_PYTHON=OFF -DLIBXML2_WITH_READER=ON -DLIBXML2_WITH_REGEXPS=ON -DLIBXML2_WITH_SAX1=ON -DLIBXML2_WITH_SCHEMAS=ON -DLIBXML2_WITH_SCHEMATRON=ON -DLIBXML2_WITH_THREADS=ON -DLIBXML2_WITH_THREAD_ALLOC=OFF -DLIBXML2_WITH_TREE=ON -DLIBXML2_WITH_VALID=ON -DLIBXML2_WITH_WRITER=ON -DLIBXML2_WITH_XINCLUDE=ON -DLIBXML2_WITH_XPATH=ON -DLIBXML2_WITH_XPTR=ON (2)
+cmake --build ./build --config Release (3)
+cmake --install ./build --prefix ./install (4)
+cd ..| 1 | +Shallow clones the libxml2 repository. | +
| 2 | +Configure the libxml2 with CMake, excluding the documentation, tests, and unwanted dependencies. | +
| 3 | +Builds libxml2 in the build directory. |
+
| 4 | +Installs libxml2 in the install directory. |
+
If you prefer using Vcpkg to install dependencies, you can install libxml2 with the following commands from the third-party directory:
Windows PowerShell
+Unix Variants
+cd vcpkg
+vcpkg.exe install libxml2[tools] --triplet x64-windows (1)| 1 | +Installs libxml2. |
+
cd vcpkg
+./vcpkg install libxml2[tools] (1)| 1 | +Installs libxml2. |
+
| + + | +
+These examples assume VcPkg is already installed in the third-party/vcpkg directory (see the Fmt section).
+ |
+
MrDocs uses LLVM to parse C++ code and extract documentation from it. +It depends on a recent version of LLVM: e1065370
+Download:
+You can shallow-clone the project from the official repository.
+From the third-party directory, run the following commands:
mkdir -p llvm-project (1)
+cd llvm-project
+git init (2)
+git remote add origin https://github.com/llvm/llvm-project.git (3)
+git fetch --depth 1 origin e1065370aaacb1b1cb48e77d37d376bf024f4a39 (4)
+git checkout FETCH_HEAD (5)| 1 | +Create a directory for the llvm-project instead of cloning it | +
| 2 | +Initialize a git repository | +
| 3 | +Add the official LLVM repository as a remote | +
| 4 | +Fetch the commit we want to use: this allows us to shallow-clone the repository at this commit | +
| 5 | +Checkout the commit we want to use | +
Configure:
+The mrdocs/third-party/llvm directory provides CMake presets to build LLVM.
+We recommend using preset files as they contain a replicable set of CMake configuration values that can be used for a project.
+From third-party/llvm-project, you can copy the CMakePresets.json and CMakeUserPresets.json files to the llvm-project/llvm directory.
cp ../../mrdocs/third-party/llvm/CMakePresets.json ./llvm
+cp ../../mrdocs/third-party/llvm/CMakeUserPresets.json ./llvm/CMakeUserPresets.jsonRun a command such as the following to configure LLVM:
+Windows PowerShell
+Unix Variants
+cd llvm
+cmake -S . -B ./build --preset=release-wincd llvm
+cmake -S . -B ./build --preset=release-unixIn the example above, we configure a Release version of LLVM for MrDocs.
+Choose one of the presets from CMakePresets.json or edit the variants in CMakeUserPresets.json to customize the configurations.
| + + | +
+
+
+Developers might also want to build a custom
+
+This should give you an optimized build with all debug features and flags, such as an appropriate |
+
Build:
+Build and install the configured version of LLVM with:
+cmake --build ./build --config Release --parallel 4
+cmake --install ./build --prefix ../installReplace 4 with the number of cores you want to use for building LLVM.
+Return from ./third-party/llvm-project/llvm to the LLVM project directory:
cd ../..In addition to LLVM, MrDocs requires a deterministic version of the C standard library (LibC) to ensure consistent behavior across various environments. This step is crucial for replicating specific compiler and library configurations.
+Download:
+Continue using the same LLVM project directory.
+Configure:
+Configure and build LibC++ using the existing structure:
+export CXX="./install/bin/clang++"
+export CC="./install/bin/clang"These options set the C and C++ compilers to the ones previously installed by LLVM. +MrDocs only depends on the LibC++ headers, so any compiler that works for this step should be fine.
+Run a command such as the following to configure LLVM:
+Windows PowerShell
+Unix Variants
+cmake -G Ninja \
+ -S runtimes \
+ -B build-libcxx \
+ -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi" \
+ -DCMAKE_INSTALL_PREFIX="$(pwd)/install" \
+ -DLIBCXXABI_USE_LLVM_UNWINDER=OFF \
+ -DLIBCXXABI_ENABLE_SHARED=OFF \
+ -DLIBCXXABI_ENABLE_STATIC=ON \
+ -DLIBCXX_ENABLE_SHARED=OFF \
+ -DLIBCXX_NO_VCRUNTIME=ON \
+ -DCMAKE_CXX_FLAGS="-D__ORDER_LITTLE_ENDIAN__=1234 -D__ORDER_BIG_ENDIAN__=4321 -D__BYTE_ORDER__=__ORDER_LITTLE_ENDIAN__"cmake -G Ninja \
+ -S runtimes \
+ -B build-libcxx \
+ -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind" \
+ -DCMAKE_INSTALL_PREFIX="$(pwd)/install"Build:
+Build and install the configured version of LibC++ with:
+Windows PowerShell
+Unix Variants
+ninja -C build-libcxx cxx
+ninja -C build-libcxx install-cxxninja -C build-libcxx cxx cxxabi unwind
+ninja -C build-libcxx install-cxx install-cxxabi install-unwindReturn from ./third-party/llvm-project to the parent directory to build and install MrDocs:
cd ../..Return from ./third-party/vcpkg to the parent directory of third-party (the one containing the mrdocs directory) to build and install MrDocs:
cd ../..Configure:
+You can also configure MrDocs with command line arguments or CMake presets.
+Configure with Command Line Arguments:
+With the dependencies are available in third-party, you can configure MrDocs with:
Windows PowerShell
+Unix Variants
+cmake -S mrdocs -B build -G "Visual Studio 17 2022" -A x64 -D CMAKE_CONFIGURATION_TYPES="RelWithDebInfo" -D CMAKE_EXPORT_COMPILE_COMMANDS=ON -D LLVM_ROOT="%cd%/third-party/llvm+clang/RelWithDebInfo" -D DUKTAPE_SOURCE_ROOT="%cd%/third-party/duktape-2.7.0" -D CMAKE_TOOLCHAIN_FILE="%cd%/third-party/vcpkg/scripts/buildsystems/vcpkg.cmake"cmake -S mrdocs -B build -D CMAKE_BUILD_TYPE=RelWithDebInfo -D CMAKE_EXPORT_COMPILE_COMMANDS=ON -D LLVM_ROOT="$(pwd)/third-party/llvm+clang/RelWithDebInfo" -D DUKTAPE_SOURCE_ROOT="$(pwd)/third-party/duktape-2.7.0" -D CMAKE_TOOLCHAIN_FILE="$(pwd)/third-party/vcpkg/scripts/buildsystems/vcpkg.cmake"Configure with CMake Presets:
+The MrDocs repository also includes a CMakePresets.json file that contains the parameters to configure MrDocs with CMake.
To specify the installation directories, you can use the LLVM_ROOT, DUKTAPE_SOURCE_ROOT, CMAKE_TOOLCHAIN_FILE environment variables.
+To specify a generator (-G) and platform name (-A), you can use the CMAKE_GENERATOR and CMAKE_GENERATOR_PLATFORM environment variables.
You can also customize the presets by duplicating and editing the CMakeUserPresets.json.example file in the mrdocs directory.
+This is typically more convenient than using environment variables.
Build:
+Then build and install MrDocs with:
+cd build
+cmake --build .
+cmake --install .To customize the installation directory, use the CMAKE_INSTALL_PREFIX option or use the --prefix option for the cmake --install . command.
+To customize the C and C++ compilers, use the CMAKE_C_COMPILER and CMAKE_CXX_COMPILER options.
| + + | +
+
+
+Developers should also enable |
+
The MrDocs installation directory follows the "Filesystem Hierarchy Standard" (FHS) layout:
+bin: the MrDocs executable intended to be used by users or invoked from the command line.
share: resource files installed by MrDocs
doc: the MrDocs documentation
include: the MrDocs headers
lib: the MrDocs library
The FHS layout provides a directory structure that also serves as a widely accepted convention for organizing files and directories in Unix-like systems, but that can be used in any operating system.
+==============================================================================
+The LLVM Project is under the Apache License v2.0 with LLVM Exceptions:
+==============================================================================
+
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright [yyyy] [name of copyright owner]
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+
+---- LLVM Exceptions to the Apache 2.0 License ----
+
+As an exception, if, as a result of your compiling your source code, portions
+of this Software are embedded into an Object form of such source code, you
+may redistribute such embedded portions in such Object form without complying
+with the conditions of Sections 4(a), 4(b) and 4(d) of the License.
+
+In addition, if you combine or link compiled forms of this Software with
+software that is licensed under the GPLv2 ("Combined Software") and if a
+court of competent jurisdiction determines that the patent provision (Section
+3), the indemnity provision (Section 9) or other Section of the License
+conflicts with the conditions of the GPLv2, you may retroactively and
+prospectively choose to deem waived or otherwise exclude such Section(s) of
+the License, but only in their entirety and only with respect to the Combined
+Software.
+
+==============================================================================
+Software from third parties included in the LLVM Project:
+==============================================================================
+The LLVM Project contains third party software which is under different license
+terms. All such code will be identified clearly using at least one of two
+mechanisms:
+1) It will be in a separate directory tree with its own `LICENSE.txt` or
+ `LICENSE` file at the top containing the specific license and restrictions
+ which apply to that software, or
+2) It will contain specific license and restriction terms at the top of every
+ file.
+
+==============================================================================
+Legacy LLVM License (https://llvm.org/docs/DeveloperPolicy.html#legacy):
+==============================================================================
+University of Illinois/NCSA
+Open Source License
+
+Copyright (c) 2003-2019 University of Illinois at Urbana-Champaign.
+All rights reserved.
+
+Developed by:
+
+ LLVM Team
+
+ University of Illinois at Urbana-Champaign
+
+ http://llvm.org
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal with
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+ * Redistributions of source code must retain the above copyright notice,
+ this list of conditions and the following disclaimers.
+
+ * Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimers in the
+ documentation and/or other materials provided with the distribution.
+
+ * Neither the names of the LLVM Team, University of Illinois at
+ Urbana-Champaign, nor the names of its contributors may be used to
+ endorse or promote products derived from this Software without specific
+ prior written permission.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS WITH THE
+SOFTWARE.The mrdocs.yml configuration file contains information about the project.
+If you’re used to Doxygen, this file is similar to the Doxyfile configuration file.
Here is an example of a mrdocs.yml file:
source-root: ../include
+multipage: false
+generate: adocIn many projects, it is common to have the documentation in a docs directory, which can also contain this configuration file.
+ <project-directory>
+ + docs
+ + mrdocs.yml
+ + ...
+ + include
+ + src
+ + test
+ + ...The most important information is the source-root option, which determines the root of the source tree relative to the mrdocs.yml file.
The list of all available options can be found in the The Configuration File page.
+| + + | +
+For consistency, these instructions assume you have the mrdocs executable in PATH.
+ |
+
You can invoke MrDocs from the command line with the following command:
+mrdocs path/to/mrdocs.ymlIf you are at the path of the mrdocs.yml file, you can simply run:
mrdocsYou can also specify other commands to MrDocs directly from the command line to set or override options from the mrdocs.yml file (See all options in The Configuration File page).
mrdocs path/to/mrdocs.yml --output=../docs/reference| + + | +
+Except for the path to the mrdocs.yml file, all other relative paths are made absolute relative to the mrdocs.yml file.
+ |
+
One way to simplify the documentation generation process is by using a compile_commands.json file generated by CMake to determine the source files to process and their compile options.
+This file is generated by the CMake configuration step when the CMAKE_EXPORT_COMPILE_COMMANDS option is set to ON.
cmake -B build -S . -DCMAKE_EXPORT_COMPILE_COMMANDS=ONAt this step, you can also add any other flags you want to pass to cmake, such as -DCMAKE_BUILD_TYPE=Release or -DCMAKE_CXX_COMPILER=clang++.
| + + | +
+If you are using the Visual Studio generator, you might need to switch to the Ninja generator to generate the compile_commands.json file.
+ |
+
This will generate a compile_commands.json file in the build directory containing all commands needed to compile your project.
+This file can be used by MrDocs to determine the source files to process and their compile options.
mrdocs --compilation-database=../build/compile_commands.json --output=../docs/referenceMrDocs will go through all the source files listed in the compile_commands.json file and generate the documentation for them.
| + + | ++When MrDocs goes through the commands in the compilation database, it will go through the same targets as the compiler. +Only symbols present in these targets will be documented. +In the case of header-only libraries, the symbols will be documented only if they are included in one of these targets. + | +
It’s common to have different configurations for the documentation generation than for the project build.
+This means CMake is often being run just to generate a custom compile_commands.json for the documentation.
+Also, the compile_commands.json file is a configuration artifact, which means it often lacks a stable location that can be referenced in the mrdocs.yml configuration file.
Thus, the pattern of using a compile_commands.json file generated by CMake is so common that MrDocs provides a CMake module to simplify the process.
+You can let MrDocs generate the compile_commands.json file for you by providing the path to the CMakeLists.txt file of your project.
mrdocs --compilation-database=../CMakeLists.txt --output=../docs/referenceBy providing your CMakeLists.txt file as the reference for you compilation database, MrDocs will automatically run CMake to generate the compile_commands.json file in a temporary directory.
+Not only this simplifies the usage but also ensures that the stable compilation database file can be used in the mrdocs.yml configuration file.
| + + | ++MrDocs does not bundle CMake. +If you want to use this feature, you need to have CMake installed on your system and available in PATH. + | +
Parameters for cmake, such as -D BUILDING_TEST=OFF -D MRDOCS_BUILD=ON can also be specified with the cmake option in configuration file.
+MrDocs will always append the CMAKE_EXPORT_COMPILE_COMMANDS=ON flag to the cmake command.
In many projects, a common pattern is to define a special build configuration for the documentation generation such that:
+Tests, examples, and auxiliary targets excluded
+All header-only files are included in targets
+Unnecessary sources files are excluded from targets
+This can usually be achieved by defining a custom target in the CMakeLists.txt with a single source file that includes all the necessary header files.
if (MY_PROJECT_MRDOCS_BUILD)
+ # Glob all header files
+ set(INCLUDE_DIR "${CMAKE_SOURCE_DIR}/include")
+ file(GLOB_RECURSE HEADER_FILES "${INCLUDE_DIR}/*.hpp")
+
+ # Create a temporary source file that includes all header files
+ set(TEMP_CPP_FILE "${CMAKE_CURRENT_BINARY_DIR}/all_headers.cpp")
+ file(WRITE ${TEMP_CPP_FILE} "// This file is generated automatically by CMake\n\n")
+ foreach(HEADER_FILE ${HEADER_FILES_LIST})
+ file(APPEND ${TEMP_CPP_FILE} "#include \"${HEADER_FILE}\"\n")
+ endforeach()
+
+ # Create a custom target for MrDocs
+ add_library(my_project_mrdocs_target ${TEMP_CPP_FILE})
+
+ # Set any other target properties here
+ target_include_directories(my_project_mrdocs_target PRIVATE ${INCLUDE_DIR})
+ target_link_libraries(my_project_mrdocs_target PRIVATE an_external_library)
+
+ # Don't create any other targets
+ return()
+endif()To use this target, you can run CMake with the MY_PROJECT_MRDOCS_BUILD flag set to ON:
mrdocs --cmake="-D MY_PROJECT_MRDOCS_BUILD=ON" --compilation-database=../CMakeLists.txt --output=..\docs\referenceBecause these paths and options are stable, you can specify them in the mrdocs.yml configuration file.
cmake: "-D MY_PROJECT_MRDOCS_BUILD=ON"
+compilation-database: ../CMakeLists.txt
+output: ../docs/referenceUnlike other documentation generators, MrDocs only works with valid C++ code. +Instead of partially preprocessing the source files and inferring symbols from potentially ill-formed code, MrDocs relies on the compilation database and Clang to preprocess the source files.
+Thus, for each common C++ construct, MrDocs provides commands or options to identify and extract the relevant information as intended by the user. +For instance, a common ill-formed Doxygen pattern to specify a class as an implementation detail is:
+#ifdef DOCS
+__implementation_defined__
+#else
+impl::f_return_t
+#endif
+f();In this pattern, the user wants to document the function f as implementation_defined f(); because the library contract is that the user should not rely on a specific return type here.
+However, this ill-formed pattern is problematic:
implementation_defined is not a valid symbol so the code is ill-formed
impl::f_return_t doesn’t express the intent of the user for the documentation
the developer has to effectively maintain two versions of the code
+the original source code becomes more and more unreadable
+Instead, when using MrDocs, the same function could be documented as:
+impl::f_return_t f();And the user can specify that impl as a namespace for implementation details in the configuration file:
# ...
+implementation-detail: impl
+# ...The Commands and The Configuration File pages contain a list of all available commands and options to identify and extract the relevant information as intended by the user.
+MrDocs provides multiple mechanisms are provided to specify special C++ patterns, such as the example above. +For each common C++ construct that would require macros and two versions of the code, MrDocs provides commands to identify the construct and extract the relevant information as intented by the user.
+MrDocs is a C++ documentation generator for your projects.
++ + Get started + + + Download + +
+No workarounds: A tool that fully understands C++
Mr. Docs takes a specially formatted comment, called a Javadoc, which precedes a C++ declaration and renders it to form a reference as part of documentation.
+Mr. Docs understands C++: Overload sets, private APIs, Concepts and constraints, unspecified return types, aliases, constants, SFINAE, hidden base classes, niebloids, and coroutines.
+Choose from multiple output formats: Asciidoc, HTML, or XML.
+Mr. Docs is highly customizable. You can change the output format, the theme, and even the way the documentation is generated.
+Boost.URL Antora documentation.
+Boost.URL multi-page Asciidoc documentation.
+Boost.URL single-page Asciidoc documentation.
+Boost.URL single-page HTML documentation.
+Boost.URL XML documentation.
+Boost.Scope multi-page Asciidoc documentation.
+Boost.Scope single-page Asciidoc documentation.
+/** Exit the program.
+
+ The program will end immediately.
+
+ @note This function does not return.
+*/
+[[noreturn]]
+void
+terminate() noexcept;Exit the program.
+Declared in header <terminate.cpp>
void
+terminate() noexcept;The program will end immediately.
+|
+ Note
+ |
++This function does not return. + | +
/** Return the distance between two points
+
+ This function returns the distance between two points
+ according to the Euclidean distance formula.
+
+ @param x0 The x-coordinate of the first point
+ @param y0 The y-coordinate of the first point
+ @param x1 The x-coordinate of the second point
+ @param y1 The y-coordinate of the second point
+ @return The distance between the two points
+*/
+double
+distance(double x0, double y0, double x1, double y1);Return the distance between two points
+Declared in header <distance.cpp>
double
+distance(
+ double x0,
+ double y0,
+ double x1,
+ double y1);This function returns the distance between two points +according to the Euclidean distance formula.
+The distance between the two points
+| Name | +Description | +
|---|---|
x0 |
+The x-coordinate of the first point |
+
y0 |
+The y-coordinate of the first point |
+
x1 |
+The x-coordinate of the second point |
+
y1 |
+The y-coordinate of the second point |
+
/** Return true if a number is prime.
+
+ @par Complexity
+
+ Linear in n.
+
+ @return Whether or not n is prime.
+ @param n The number to test
+
+*/
+bool
+is_prime(unsigned long long n) noexcept;Return true if a number is prime.
+Declared in header <is_prime.cpp>
bool
+is_prime(unsigned long long n) noexcept;Linear in n.
+Whether or not n is prime.
+| Name | +Description | +
|---|---|
n |
+The number to test |
+
#include <type_traits>
+#include <stdexcept>
+
+/** Computes the square root of an integral value.
+
+ This function calculates the square root of a
+ given integral value using bit manipulation.
+
+ @throws std::invalid_argument if the input value is negative.
+
+ @tparam T The type of the input value. Must be an integral type.
+ @param value The integral value to compute the square root of.
+ @return The square root of the input value.
+ */
+template <typename T>
+std::enable_if_t<std::is_integral_v<T>, T> sqrt(T value) {
+ if (value < 0) {
+ throw std::invalid_argument(
+ "Cannot compute square root of a negative number");
+ }
+ T result = 0;
+ // The second-to-top bit is set
+ T bit = 1 << (sizeof(T) * 8 - 2);
+ while (bit > value) bit >>= 2;
+ while (bit != 0) {
+ if (value >= result + bit) {
+ value -= result + bit;
+ result += bit << 1;
+ }
+ result >>= 1;
+ bit >>= 2;
+ }
+ return result;
+}
+Computes the square root of an integral value.
+Declared in header <sqrt.cpp>
template<typename T>
+T
+sqrt(T value);This function calculates the square root of a +given integral value using bit manipulation.
+| Name | +Thrown on | +
|---|---|
|
+the input value is negative. |
+
The square root of the input value.
+| Name | +Description | +
|---|---|
T |
+The type of the input value. Must be an integral type. |
+
| Name | +Description | +
|---|---|
value |
+The integral value to compute the square root of. |
+
Give us a Star on GitHub: + +
+