Skip to content

Commit 18818c9

Browse files
gennaroprotagennaroprota
committed
test: regression for the extract-all crash (issue #1195)
`checkUndocumented` used to call `undocumented_.erase(it)` without first checking `it != end()`. Under `extract-all: false`, `undocumented_` never gets populated, so for any documented symbol `find()` returned `end()` and the unguarded erase was undefined behavior. A user reported this as a crash in v0.8.0. b103cba fixed this as part of an unrelated restructuring, but the existing fixture in this directory disabled `warn-if-undocumented` and so never reached the crashy block. The new fixture combines `extract-all: false` with the default `warn-if-undocumented: true` and includes a documented record. Closes issue #1195.
1 parent ab5f412 commit 18818c9

5 files changed

Lines changed: 240 additions & 0 deletions

File tree

‎test-files/golden-tests/config/extract-all/warn-when-undocumented.adoc‎

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

‎test-files/golden-tests/config/extract-all/warn-when-undocumented.cpp‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
// Regression test for the crash described in
2+
// https://github.com/cppalliance/mrdocs/issues/1195.
3+
//
4+
// Earlier versions of `checkUndocumented` called `undocumented_.erase(it)`
5+
// without checking `it != end()`. With `extract-all: false` and a documented
6+
// symbol, the lookup misses (the set is empty under that config) and the
7+
// unchecked erase is undefined behaviour. `warn-if-undocumented` must be left
8+
// at its default true here so the buggy block is reached.
9+
10+
/// A documented struct.
11+
struct Documented {};
12+
13+
struct Undocumented {};
14+
15+
/// A documented function.
16+
void documentedFunction();
17+
18+
void undocumentedFunction();

‎test-files/golden-tests/config/extract-all/warn-when-undocumented.html‎

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

‎test-files/golden-tests/config/extract-all/warn-when-undocumented.xml‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
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>
5+
<source>
6+
</source>
7+
<kind>namespace</kind>
8+
<id>//////////////////////////8=</id>
9+
<extraction>regular</extraction>
10+
<namespace-tranche>
11+
<records>1Oafq0Qg8PKbrn4hwQwSeK44I44=</records>
12+
<functions>IX3R+wr9jgB/i1gRciE8tyKKkOY=</functions>
13+
</namespace-tranche>
14+
</namespace>
15+
<record>
16+
<name>Documented</name>
17+
<source>
18+
<location>
19+
<short-path>warn-when-undocumented.cpp</short-path>
20+
<source-path>warn-when-undocumented.cpp</source-path>
21+
<line-number>11</line-number>
22+
<column-number>1</column-number>
23+
<documented>1</documented>
24+
</location>
25+
</source>
26+
<kind>record</kind>
27+
<id>1Oafq0Qg8PKbrn4hwQwSeK44I44=</id>
28+
<extraction>regular</extraction>
29+
<parent>//////////////////////////8=</parent>
30+
<doc-comment>
31+
<brief>
32+
<kind>brief</kind>
33+
<text>
34+
<kind>text</kind>
35+
<literal>A documented struct.</literal>
36+
</text>
37+
</brief>
38+
</doc-comment>
39+
<key-kind>struct</key-kind>
40+
<record-interface>
41+
<record-tranche>
42+
</record-tranche>
43+
<record-tranche>
44+
</record-tranche>
45+
<record-tranche>
46+
</record-tranche>
47+
</record-interface>
48+
</record>
49+
<function>
50+
<name>documentedFunction</name>
51+
<source>
52+
<location>
53+
<short-path>warn-when-undocumented.cpp</short-path>
54+
<source-path>warn-when-undocumented.cpp</source-path>
55+
<line-number>16</line-number>
56+
<column-number>1</column-number>
57+
<documented>1</documented>
58+
</location>
59+
</source>
60+
<kind>function</kind>
61+
<id>IX3R+wr9jgB/i1gRciE8tyKKkOY=</id>
62+
<extraction>regular</extraction>
63+
<parent>//////////////////////////8=</parent>
64+
<doc-comment>
65+
<brief>
66+
<kind>brief</kind>
67+
<text>
68+
<kind>text</kind>
69+
<literal>A documented function.</literal>
70+
</text>
71+
</brief>
72+
</doc-comment>
73+
<named>
74+
<name>
75+
<kind>identifier</kind>
76+
<identifier>void</identifier>
77+
</name>
78+
</named>
79+
<func-class>normal</func-class>
80+
</function>
81+
</mrdocs>

‎test-files/golden-tests/config/extract-all/warn-when-undocumented.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
extract-all: false
2+
warn-if-undocumented: true

0 commit comments

Comments
 (0)