You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/modules/ROOT/pages/contribute.adoc
+8-8Lines changed: 8 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,23 +1,23 @@
1
1
= Contributor's Guide
2
2
3
-
This page contains information for contributors to the MrDocs project.
3
+
This page contains information for contributors to the Mr.Docs project.
4
4
It is intended to provide an overview of the codebase and the process of adding new features.
5
5
6
6
== Codebase Overview
7
7
8
-
The MrDocs codebase is divided into several modules:
8
+
The Mr.Docs codebase is divided into several modules:
9
9
10
10
include::partial$workflow.adoc[]
11
11
12
-
This section provides an overview of each module and how they interact with each other in the MrDocs codebase.
12
+
This section provides an overview of each module and how they interact with each other in the Mr.Docs codebase.
13
13
14
14
[#options]
15
15
=== Parsing options
16
16
17
-
MrDocs options affect the behavior of the compilation database, how symbols are extracted, and how the documentation is generated.
17
+
Mr.Docs options affect the behavior of the compilation database, how symbols are extracted, and how the documentation is generated.
18
18
They are parsed from the command line and configuration file.
19
19
20
-
The main entry point of MrDocs is the `DoGenerateAction` function in `src/tool/GenerateAction.cpp`.
20
+
The main entry point of Mr.Docs is the `DoGenerateAction` function in `src/tool/GenerateAction.cpp`.
21
21
It loads the options, creates the compilation database, and runs the extraction and generation steps.
22
22
The options are formed from a combination of command line arguments and configuration file settings.
23
23
@@ -34,7 +34,7 @@ It also provides a representation plugins can use to access public options from
34
34
35
35
The function `clang::mrdocs::loadConfig` is also provided to parse all public options from a YAML configuration file.
36
36
37
-
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.
37
+
Internally, Mr.Docs uses the derived `clang::mrdocs::ConfigImpl` class (`src/lib/Lib/ConfigImpl.hpp`) to also store the private representation of parsed options, such as filters.
38
38
39
39
==== Finalizing Options
40
40
@@ -56,9 +56,9 @@ The AST information is extracted and stored in a `Corpus` object (`mrdocs/Corpus
56
56
==== Compilation Database
57
57
58
58
The second step in `DoGenerateAction` is to create a `CompilationDatabase` object, so we can extract symbols from its source files.
59
-
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.
59
+
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 Mr.Docs from build scripts.
60
60
61
-
Whatever the source, a derived `MrDocsCompilationDatabase` object (`lib/Lib/MrDocsCompilationDatabase.hpp`) is created to represent the compilation database.
61
+
Whatever the source, a derived `Mr.DocsCompilationDatabase` object (`lib/Lib/Mr.DocsCompilationDatabase.hpp`) is created to represent the compilation database.
62
62
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.
Copy file name to clipboardExpand all lines: docs/modules/ROOT/pages/design-notes.adoc
+15-11Lines changed: 15 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,7 +3,7 @@
3
3
== Why automate documentation?
4
4
5
5
{cpp} API design is challenging.
6
-
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.
6
+
When you write a function signature or declare a class, it is at that moment that you are likely to have as much information as you will ever have about what it is supposed to do.
7
7
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.
8
8
9
9
In other words, because best and worst engineers are naturally lazy, the *temporal adjacency* of the {cpp} declaration to the documentation improves outcomes.
@@ -17,11 +17,11 @@ In summary, the automated extraction of reference documentation from {cpp} decla
17
17
* And causally connected documentation is more accurate
18
18
19
19
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.
20
-
However, {cpp} 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.
20
+
However, {cpp} codebases are notoriously challenging to document automatically because of constructs where the code needs to diverge from the intended API that represents the contract with the user.
21
21
22
-
Tools like Doxygen typically require workarounds and manual intervention via preprocessor macros to get the documentation right.
23
-
These workarounds are problematic because they effectively mean that there are two versions of the code: the well-formed and the ill-formed versions.
24
-
This subverts the single sources of truth for the code.
22
+
Tools like Doxygen typically require workarounds and manual intervention via preprocessor macros to produce accurate documentation.
23
+
These workarounds are problematic because they result in two versions of the code: the well-formed and the ill-formed versions.
24
+
This subverts the single source of truth for the code.
25
25
26
26
|===
27
27
| | Mr. Docs | Automatic | Manual | No Reference
@@ -38,35 +38,39 @@ This is a problem because header files are not always the best source of truth f
38
38
Developers familiar with https://cppreference.com[cppreference.com,window=_blank] will know that the documentation there is often more informative than the header files.
39
39
* A common alternative is to provide a manual reference to the API.
40
40
Developers duplicate the signatures, which requires extra work.
41
-
This strategy tends to work well for small libraries and allows the developer to directly express the contract with the user.
41
+
This strategy tends to work well for small libraries and allows the developer to express the contract with the user directly.
42
42
However, as the single source of truth is lost, it becomes unmanageable as the codebase grows.
43
43
When the declaration changes, they forget to edit the docs, and the reference becomes out of date.
44
44
* In this case, it looks like the best solution is to automate the documentation.
45
45
The causal connection between the declaration and the generated documentation improves outcomes.
46
-
That's when developers face difficulties with existing tools like Doxygen, which require workarounds and manual intervention to get the documentation right.
46
+
That's when developers face difficulties with existing tools like Doxygen, which require workarounds and manual intervention to produce accurate documentation.
47
47
The workarounds mean that there are two versions of the code: the well-formed and the ill-formed versions.
48
-
* 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.
48
+
* The philosophy behind Mr.Docs is to provide solutions to these workarounds so that the single source of truth can be maintained with minimal effort by developers.
49
49
With Mr.Docs, the documented {cpp} code should be the same as the code that is compiled.
50
50
51
51
== Customization
52
52
53
53
Once the documentation is extracted from the code, it is necessary to format it in a way that is useful to the user.
54
-
This usually involves generating output files that match the content of the documentation to the user's needs.
54
+
This usually involves generating output files that match the documentation's content to the user's needs.
55
55
56
56
A limitation of existing tools like Doxygen is that their output formats are not very customizable.
57
57
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.
58
58
59
-
MrDocs attempts to support multiple output formats and customization options.
59
+
MrDocs supports multiple output formats and customization options.
60
60
In practice, MrDocs attempts to provide three levels of customization:
61
61
62
62
* At the first level, the user can use an existing generator and customize its templates and helper functions.
63
63
* The user can write a MrDocs plugin at a second level that defines a new generator.
64
64
* 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.
65
65
66
-
These multiple levels of complexity mean developers can worry only about the documentation content.
66
+
These multiple levels of complexity mean developers can focus solely on the documentation content.
67
67
In practice, developers rarely need new generators and are usually only interested in changing how an existing generator formats the output.
68
68
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.
69
69
70
+
=== Custom Main Pages
71
+
72
+
This customized design means MrDocs does not need to support custom main pages directly. Instead, you can create your own by writing your markup files. These pages are authored entirely by the user and can be seamlessly combined with the MrDocs output, since the output is designed to be customized to your needs.
73
+
70
74
== {cpp} Constructs
71
75
72
76
To deal with the complexity of {cpp} constructs, MrDocs uses clang's libtooling API.
Copy file name to clipboardExpand all lines: docs/modules/ROOT/pages/generators.adoc
+5-5Lines changed: 5 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
= Generators
2
2
3
-
MrDocs uses a generator to convert the extracted symbols into documentation.
4
-
MrDocs supports multiple output formats that can be specified via the `generate` option:
3
+
Mr.Docs uses a generator to convert the extracted symbols into documentation.
4
+
Mr.Docs supports multiple output formats that can be specified via the `generate` option:
5
5
6
6
The `generator` option can be used to specify the output format:
7
7
@@ -42,7 +42,7 @@ HTML can be generated directly with the `html` format.
42
42
43
43
== Choosing the Right Generator
44
44
45
-
The scatter plot below illustrates the available output formats for MrDocs, along with hypothetical solutions, in terms of **redundancy** and **convenience**.
45
+
The scatter plot below illustrates the available output formats for Mr.Docs, along with hypothetical solutions, in terms of **redundancy** and **convenience**.
- However, documenting {cpp} poses significant challenges due to discrepancies between the codebase and the public API. Doxygen remains a popular tool, yet it is suboptimal for {cpp} as it fails to fully comprehend {cpp} constructs and requires many transformation steps, including the incorporation of many macros within the {cpp} code. These macros maintain well-formed and ill-formed versions of the code, undermining the goal of unifying the source of truth.
13
13
- Existing solutions frequently need better maintenance or usability issues, prompting users to revert to Doxygen.
14
14
- An ideal solution would inherently understand {cpp} constructs, be actively maintained, and offer diverse options for customizing the output format.
15
-
- MrDocs embodies these qualities. Supported by full-time developers from the {cpp} Alliance, MrDocs inherently comprehends {cpp} 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.
15
+
- Mr.Docs embodies these qualities. Supported by full-time developers from the {cpp} Alliance, Mr.Docs inherently comprehends {cpp} 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.
0 commit comments