Skip to content

Fix some glitches in the documentation #916

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/modules/ROOT/pages/contribute.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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`).
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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:

Expand Down
2 changes: 1 addition & 1 deletion docs/modules/ROOT/pages/install.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
8 changes: 4 additions & 4 deletions docs/modules/ROOT/pages/usage.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand All @@ -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

Expand Down Expand Up @@ -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++]
----
Expand All @@ -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]
Expand Down
Loading