Skip to content

Commit 7681b72

Browse files
alandefreitasalandefreitas
committed
extract-all option
#feat fix #758
1 parent 5185e7c commit 7681b72

File tree

8 files changed

+235
-28
lines changed

8 files changed

+235
-28
lines changed

‎docs/mrdocs.schema.json

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,16 @@
9191
"title": "Symbol patterns to exclude",
9292
"type": "array"
9393
},
94+
"extract-all": {
95+
"default": true,
96+
"description": "When set to `true`, MrDocs extracts all symbols from the source code, even if no documentation is provided. When set to `false`, it's still recommendable to provide file and symbol filters so that only the desired symbols are traversed by MrDocs.",
97+
"enum": [
98+
true,
99+
false
100+
],
101+
"title": "Extract all symbols",
102+
"type": "boolean"
103+
},
94104
"file-patterns": {
95105
"default": [
96106
"*.hpp",

‎src/lib/AST/ASTVisitor.cpp

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3271,6 +3271,11 @@ Expected<
32713271
ASTVisitor::
32723272
upsert(DeclType const* D)
32733273
{
3274+
using R = std::conditional_t<
3275+
std::same_as<InfoTy, void>,
3276+
InfoTypeFor_t<DeclType>,
3277+
InfoTy>;
3278+
32743279
ExtractionMode const m = checkFilters(D);
32753280
if (m == ExtractionMode::Dependency)
32763281
{
@@ -3286,14 +3291,17 @@ upsert(DeclType const* D)
32863291
return Unexpected(Error("Explicit declaration in dependency mode"));
32873292
}
32883293
}
3294+
else if (
3295+
!InfoParent<R> &&
3296+
mode_ == Regular &&
3297+
!config_->extractAll &&
3298+
!D->getASTContext().getRawCommentForDeclNoCache(D))
3299+
{
3300+
return Unexpected(formatError("{}: Symbol is undocumented", extractName(D)));
3301+
}
32893302

32903303
SymbolID const id = generateID(D);
32913304
MRDOCS_CHECK_MSG(id, "Failed to extract symbol ID");
3292-
3293-
using R = std::conditional_t<
3294-
std::same_as<InfoTy, void>,
3295-
InfoTypeFor_t<DeclType>,
3296-
InfoTy>;
32973305
auto [I, isNew] = upsert<R>(id);
32983306

32993307
// Already populate the extraction mode

‎src/lib/Lib/ConfigOptions.json

Lines changed: 44 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -159,22 +159,43 @@
159159
}
160160
]
161161
},
162+
{
163+
"category": "Comment Parsing",
164+
"brief": "Options to control how comments are parsed",
165+
"details": "MrDocs extracts metadata from the comments in the source code. The following options control how comments are parsed.",
166+
"options": [
167+
{
168+
"name": "auto-brief",
169+
"brief": "Use the first line of the comment as the brief",
170+
"details": "When set to `true`, MrDocs uses the first line (until the first dot, question mark, or exclamation mark) of the comment as the brief of the symbol. When set to `false`, a explicit @brief command is required.",
171+
"type": "bool",
172+
"default": true
173+
}
174+
]
175+
},
162176
{
163177
"category": "Metadata Extraction",
164178
"brief": "Metadata and C++ semantic constructs to extract",
165179
"details": "MrDocs extracts metadata and C++ semantic constructs from the source code to create the documentation. Semantic constructs are patterns not directly represented in the source code AST but can be inferred from the corpus, such as SFINAE. The following options control the extraction of metadata and C++ semantic constructs.",
166180
"options": [
167181
{
168-
"name": "sfinae",
169-
"brief": "Detect and reduce SFINAE expressions",
170-
"details": "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. MrDocs uses an algorithm that extracts SFINAE infomation from types by identifying inspecting the primary template and specializations to detect the result type and the controlling expressions in a specialization.",
182+
"name": "extract-all",
183+
"brief": "Extract all symbols",
184+
"details": "When set to `true`, MrDocs extracts all symbols from the source code, even if no documentation is provided. When set to `false`, it's still recommendable to provide file and symbol filters so that only the desired symbols are traversed by MrDocs.",
171185
"type": "bool",
172186
"default": true
173187
},
174188
{
175-
"name": "overloads",
176-
"brief": "Detect and group function overloads",
177-
"details": "When set to `true`, MrDocs detects function overloads and groups them as a single symbol type.",
189+
"name": "private-members",
190+
"brief": "Extraction policy for private class members",
191+
"details": "Determine whether private class members should be extracted",
192+
"type": "bool",
193+
"default": false
194+
},
195+
{
196+
"name": "private-bases",
197+
"brief": "Extraction policy for private base classes",
198+
"details": "Determine whether private base classes should be extracted",
178199
"type": "bool",
179200
"default": true
180201
},
@@ -191,20 +212,6 @@
191212
],
192213
"default": "copy-dependencies"
193214
},
194-
{
195-
"name": "private-members",
196-
"brief": "Extraction policy for private class members",
197-
"details": "Determine whether private class members should be extracted",
198-
"type": "bool",
199-
"default": false
200-
},
201-
{
202-
"name": "private-bases",
203-
"brief": "Extraction policy for private base classes",
204-
"details": "Determine whether private base classes should be extracted",
205-
"type": "bool",
206-
"default": true
207-
},
208215
{
209216
"name": "anonymous-namespaces",
210217
"brief": "Extraction policy for anonymous namespaces",
@@ -253,11 +260,25 @@
253260
"details": "When set to `true`, relational operators are sorted last in the list of members of a record or namespace.",
254261
"type": "bool",
255262
"default": true
263+
}
264+
]
265+
},
266+
{
267+
"category": "Semantic Constructs",
268+
"brief": "C++ semantic constructs to extract",
269+
"details": "Semantic constructs are patterns not directly represented in the source code AST but can be inferred from the corpus, such as SFINAE.",
270+
"options": [
271+
{
272+
"name": "sfinae",
273+
"brief": "Detect and reduce SFINAE expressions",
274+
"details": "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. MrDocs uses an algorithm that extracts SFINAE infomation from types by identifying inspecting the primary template and specializations to detect the result type and the controlling expressions in a specialization.",
275+
"type": "bool",
276+
"default": true
256277
},
257278
{
258-
"name": "auto-brief",
259-
"brief": "Use the first line of the comment as the brief",
260-
"details": "When set to `true`, MrDocs uses the first line (until the first dot, question mark, or exclamation mark) of the comment as the brief of the symbol. When set to `false`, a explicit @brief command is required.",
279+
"name": "overloads",
280+
"brief": "Detect and group function overloads",
281+
"details": "When set to `true`, MrDocs detects function overloads and groups them as a single symbol type.",
261282
"type": "bool",
262283
"default": true
263284
}

‎test-files/golden-tests/config/extract-all/no-extract-all.adoc

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
= Reference
2+
:mrdocs:
3+
4+
[#index]
5+
== Global namespace
6+
7+
8+
=== Functions
9+
10+
[cols=2]
11+
|===
12+
| Name | Description
13+
14+
| <<docFunction,`docFunction`>>
15+
| Documented function
16+
17+
| <<sometimesDocFunction,`sometimesDocFunction`>>
18+
| Sometimes documented function
19+
20+
|===
21+
22+
[#docFunction]
23+
== docFunction
24+
25+
26+
Documented function
27+
28+
=== Synopsis
29+
30+
31+
Declared in `&lt;no&hyphen;extract&hyphen;all&period;cpp&gt;`
32+
33+
[source,cpp,subs="verbatim,replacements,macros,-callouts"]
34+
----
35+
void
36+
docFunction();
37+
----
38+
39+
[#sometimesDocFunction]
40+
== sometimesDocFunction
41+
42+
43+
Sometimes documented function
44+
45+
=== Synopsis
46+
47+
48+
Declared in `&lt;no&hyphen;extract&hyphen;all&period;cpp&gt;`
49+
50+
[source,cpp,subs="verbatim,replacements,macros,-callouts"]
51+
----
52+
void
53+
sometimesDocFunction();
54+
----
55+
56+
57+
58+
[.small]#Created with https://www.mrdocs.com[MrDocs]#

‎test-files/golden-tests/config/extract-all/no-extract-all.cpp

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
void undocFunction();
2+
3+
/// Documented function
4+
void docFunction();
5+
6+
void sometimesDocFunction();
7+
8+
/// Sometimes documented function
9+
void sometimesDocFunction();

‎test-files/golden-tests/config/extract-all/no-extract-all.html

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
<html lang="en">
2+
<head>
3+
<title>Reference</title>
4+
</head>
5+
<body>
6+
<div>
7+
<h1>Reference</h1>
8+
<div>
9+
<div>
10+
<h2 id="index">Global namespace</h2>
11+
</div>
12+
<h2>Functions</h2>
13+
<table style="table-layout: fixed; width: 100%;">
14+
<thead>
15+
<tr>
16+
<th>Name</th><th>Description</th>
17+
</tr>
18+
</thead>
19+
<tbody>
20+
<tr>
21+
<td><a href="#docFunction"><code>docFunction</code></a> </td><td><span><span>Documented function</span></span>
22+
23+
</td></tr><tr>
24+
<td><a href="#sometimesDocFunction"><code>sometimesDocFunction</code></a> </td><td><span><span>Sometimes documented function</span></span>
25+
26+
</td></tr>
27+
</tbody>
28+
</table>
29+
</div>
30+
<div>
31+
<div>
32+
<h2 id="docFunction">docFunction</h2>
33+
<div>
34+
<span><span>Documented function</span></span>
35+
36+
37+
</div>
38+
</div>
39+
<div>
40+
<h3>Synopsis</h3>
41+
<div>
42+
Declared in <code>&lt;no-extract-all.cpp&gt;</code></div>
43+
<pre>
44+
<code class="source-code cpp">
45+
void
46+
docFunction();
47+
</code>
48+
</pre>
49+
</div>
50+
</div>
51+
<div>
52+
<div>
53+
<h2 id="sometimesDocFunction">sometimesDocFunction</h2>
54+
<div>
55+
<span><span>Sometimes documented function</span></span>
56+
57+
58+
</div>
59+
</div>
60+
<div>
61+
<h3>Synopsis</h3>
62+
<div>
63+
Declared in <code>&lt;no-extract-all.cpp&gt;</code></div>
64+
<pre>
65+
<code class="source-code cpp">
66+
void
67+
sometimesDocFunction();
68+
</code>
69+
</pre>
70+
</div>
71+
</div>
72+
73+
</div>
74+
<div>
75+
<h4>Created with <a href="https://www.mrdocs.com">MrDocs</a></h4>
76+
</div>
77+
</body>
78+
</html>

‎test-files/golden-tests/config/extract-all/no-extract-all.xml

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<mrdocs xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3+
xsi:noNamespaceSchemaLocation="https://github.com/cppalliance/mrdocs/raw/develop/mrdocs.rnc">
4+
<namespace id="//////////////////////////8=">
5+
<function name="docFunction" id="5x56dR04az7i0nZ7FnDVQhMFz4w=">
6+
<file short-path="no-extract-all.cpp" source-path="no-extract-all.cpp" line="4"/>
7+
<doc>
8+
<brief>
9+
<text>Documented function</text>
10+
</brief>
11+
</doc>
12+
</function>
13+
<function name="sometimesDocFunction" id="zfmhYS+B5jkLgBi5x/Ciuh0zH6Y=">
14+
<file short-path="no-extract-all.cpp" source-path="no-extract-all.cpp" line="9"/>
15+
<doc>
16+
<brief>
17+
<text>Sometimes documented function</text>
18+
</brief>
19+
</doc>
20+
</function>
21+
</namespace>
22+
</mrdocs>

‎test-files/golden-tests/config/extract-all/no-extract-all.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
extract-all: false

0 commit comments

Comments
 (0)