diff --git a/docs/modules/ROOT/pages/contribute.adoc b/docs/modules/ROOT/pages/contribute.adoc index 376da2427..cdbd16b39 100644 --- a/docs/modules/ROOT/pages/contribute.adoc +++ b/docs/modules/ROOT/pages/contribute.adoc @@ -19,7 +19,7 @@ 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. +The options are formed from a combination of command line arguments and configuration file settings. ==== Command Line Options @@ -97,7 +97,7 @@ 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`. +The action object 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`). @@ -131,7 +131,7 @@ 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. +A second finalization step is then performed in `clang::mrdocs::finalize`, 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 {cpp} constructs that are not directly represented in the AST can be inferred. @@ -223,7 +223,7 @@ 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`. +* Unit testing: When no input paths are provided, all unit tests will be run via `unit_test_main()`, defined by 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: diff --git a/docs/modules/ROOT/pages/install.adoc b/docs/modules/ROOT/pages/install.adoc index ca1d5428f..70ddf70b1 100644 --- a/docs/modules/ROOT/pages/install.adoc +++ b/docs/modules/ROOT/pages/install.adoc @@ -38,7 +38,7 @@ cd third-party [NOTE] ==== These instructions assume all dependencies are installed in the `third-party` directory for simplicity. -Fell free to install them anywhere you want and adjust the main MrDocs configuration command later. +Feel free to install them anywhere you want and adjust the main MrDocs configuration command later. ==== [#install-fmt] diff --git a/docs/modules/ROOT/pages/usage.adoc b/docs/modules/ROOT/pages/usage.adoc index 7784f8249..3b67d9302 100644 --- a/docs/modules/ROOT/pages/usage.adoc +++ b/docs/modules/ROOT/pages/usage.adoc @@ -131,7 +131,7 @@ Not only this simplifies the usage but also ensures that the stable compilation NOTE: 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. +Parameters for cmake, such as `-D BUILDING_TEST=OFF -D MRDOCS_BUILD=ON` can also be specified with the `cmake` option in the configuration file. MrDocs will always append the `CMAKE_EXPORT_COMPILE_COMMANDS=ON` flag to the cmake command. [NOTE] @@ -147,7 +147,7 @@ When the `cmake` option is provided, MrDocs will still adjust the CMake configur In many projects, a common pattern is to define a special build configuration for the documentation generation such that: -1. Tests, examples, and auxiliary targets excluded +1. Tests, examples, and auxiliary targets are excluded 2. All header-only files are included in targets 3. Unnecessary sources files are excluded from targets @@ -221,7 +221,7 @@ However, this ill-formed pattern is problematic: * the developer has to effectively maintain two versions of the code * the original source code becomes more and more unreadable -Instead, when using MrDocs, while the `\\__MRDOCS__` macro is still available for conditional compilation, the same function could be directly documented as: +Instead, when using MrDocs, while the `__MRDOCS__` macro is still available for conditional compilation, the same function could be directly documented as: [source,c++] ---- @@ -239,7 +239,7 @@ implementation-defined: impl::** The xref:commands.adoc[] and xref:config-file.adoc[] 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 {cpp} patterns, such as the example above. +MrDocs provides multiple mechanisms to specify special {cpp} patterns, such as the example above. For each common {cpp} 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. [#dependencies]