Skip to content

Commit 37c127c

Browse files
dswijdswij
authored
doc_paragraphs_missing_punctuation: allow some non-punctuated paragraphs (#16487)
This fixes an FP in `doc_paragraphs_missing_punctuation` which prevented having lists (and code blocks) as parts of sentences. Even though it was often possible to rephrase to make the lint happy, it likely makes the lint more acceptable if we just allow these (at the risk of some false negatives). This fix might be a bit ad hoc, but it should make the exception pretty explicit and easy to follow. - Fixes #16370 changelog: [`doc_paragraphs_missing_punctuation`]: allow unpunctuated paragraphs before lists and code blocks --- Feel free to push to this branch as needed.
2 parents 62c5f16 + 9c1ca3a commit 37c127c

4 files changed

Lines changed: 63 additions & 41 deletions

File tree

‎clippy_lints/src/doc/doc_paragraphs_missing_punctuation.rs‎

Lines changed: 14 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -53,21 +53,26 @@ fn is_missing_punctuation(doc_string: &str) -> Vec<MissingPunctuation> {
5353
let mut no_report_depth = 0;
5454
let mut missing_punctuation = Vec::new();
5555
let mut current_paragraph = None;
56+
let mut current_event_is_missing_punctuation = false;
5657

5758
for (event, offset) in
5859
Parser::new_ext(doc_string, main_body_opts() - Options::ENABLE_SMART_PUNCTUATION).into_offset_iter()
5960
{
61+
let last_event_was_missing_punctuation = current_event_is_missing_punctuation;
62+
current_event_is_missing_punctuation = false;
63+
6064
match event {
61-
Event::Start(
62-
Tag::CodeBlock(..)
63-
| Tag::FootnoteDefinition(_)
64-
| Tag::Heading { .. }
65-
| Tag::HtmlBlock
66-
| Tag::List(..)
67-
| Tag::Table(_),
68-
) => {
65+
Event::Start(Tag::FootnoteDefinition(_) | Tag::Heading { .. } | Tag::HtmlBlock | Tag::Table(_)) => {
6966
no_report_depth += 1;
7067
},
68+
Event::Start(Tag::CodeBlock(..) | Tag::List(..)) => {
69+
no_report_depth += 1;
70+
if last_event_was_missing_punctuation {
71+
// Remove the error from the previous paragraph as it is followed by a code
72+
// block or a list.
73+
missing_punctuation.pop();
74+
}
75+
},
7176
Event::End(TagEnd::FootnoteDefinition) => {
7277
no_report_depth -= 1;
7378
},
@@ -83,6 +88,7 @@ fn is_missing_punctuation(doc_string: &str) -> Vec<MissingPunctuation> {
8388
Event::End(TagEnd::Paragraph) => {
8489
if let Some(mp) = current_paragraph {
8590
missing_punctuation.push(mp);
91+
current_event_is_missing_punctuation = true;
8692
}
8793
},
8894
Event::Code(..) | Event::Start(Tag::Link { .. }) | Event::End(TagEnd::Link)

‎tests/ui/doc/doc_paragraphs_missing_punctuation.fixed‎

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -46,13 +46,6 @@ enum Exceptions {
4646
/// | -------------- | ----- |
4747
/// | Markdown table | A-ok |
4848
MarkdownTable,
49-
/// Here is a snippet.
50-
//~^ doc_paragraphs_missing_punctuation
51-
///
52-
/// ```
53-
/// // Code blocks are no issues.
54-
/// ```
55-
CodeBlock,
5649
}
5750

5851
// Check the lint can be expected on a whole enum at once.
@@ -130,6 +123,24 @@ enum OrderedLists {
130123
Paren,
131124
}
132125

126+
/// Some elements do not have to be introduced by an independent clause.
127+
enum NotIndependentClause {
128+
/// Lists are allowed to be introduced by a clause that is not independent: this usually
129+
/// requires that
130+
///
131+
/// - items end with a comma or a semicolon, which is not enforced;
132+
/// - the last item end with a period, which is also not enforced.
133+
List,
134+
/// For instance, the function
135+
///
136+
/// ```
137+
/// fn answer() {}
138+
/// ```
139+
///
140+
/// returns the Answer to the Ultimate Question of Life, the Universe, and Everything.
141+
CodeBlock,
142+
}
143+
133144
/// Doc comments with trailing blank lines are supported.
134145
//~^ doc_paragraphs_missing_punctuation
135146
///

‎tests/ui/doc/doc_paragraphs_missing_punctuation.rs‎

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -46,13 +46,6 @@ enum Exceptions {
4646
/// | -------------- | ----- |
4747
/// | Markdown table | A-ok |
4848
MarkdownTable,
49-
/// Here is a snippet
50-
//~^ doc_paragraphs_missing_punctuation
51-
///
52-
/// ```
53-
/// // Code blocks are no issues.
54-
/// ```
55-
CodeBlock,
5649
}
5750

5851
// Check the lint can be expected on a whole enum at once.
@@ -130,6 +123,24 @@ enum OrderedLists {
130123
Paren,
131124
}
132125

126+
/// Some elements do not have to be introduced by an independent clause.
127+
enum NotIndependentClause {
128+
/// Lists are allowed to be introduced by a clause that is not independent: this usually
129+
/// requires that
130+
///
131+
/// - items end with a comma or a semicolon, which is not enforced;
132+
/// - the last item end with a period, which is also not enforced.
133+
List,
134+
/// For instance, the function
135+
///
136+
/// ```
137+
/// fn answer() {}
138+
/// ```
139+
///
140+
/// returns the Answer to the Ultimate Question of Life, the Universe, and Everything.
141+
CodeBlock,
142+
}
143+
133144
/// Doc comments with trailing blank lines are supported
134145
//~^ doc_paragraphs_missing_punctuation
135146
///

‎tests/ui/doc/doc_paragraphs_missing_punctuation.stderr‎

Lines changed: 13 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -32,82 +32,76 @@ LL | /// <https://spec.commonmark.org/0.31.2/#autolinks>
3232
| ^ help: end the paragraph with some punctuation: `.`
3333

3434
error: doc paragraphs should end with a terminal punctuation mark
35-
--> tests/ui/doc/doc_paragraphs_missing_punctuation.rs:49:26
36-
|
37-
LL | /// Here is a snippet
38-
| ^ help: end the paragraph with some punctuation: `.`
39-
40-
error: doc paragraphs should end with a terminal punctuation mark
41-
--> tests/ui/doc/doc_paragraphs_missing_punctuation.rs:72:15
35+
--> tests/ui/doc/doc_paragraphs_missing_punctuation.rs:65:15
4236
|
4337
LL | /// U+0001
4438
| ^ help: end the paragraph with some punctuation: `.`
4539

4640
error: doc paragraphs should end with a terminal punctuation mark
47-
--> tests/ui/doc/doc_paragraphs_missing_punctuation.rs:79:29
41+
--> tests/ui/doc/doc_paragraphs_missing_punctuation.rs:72:29
4842
|
4943
LL | //! inner attributes too
5044
| ^ help: end the paragraph with some punctuation: `.`
5145

5246
error: doc paragraphs should end with a terminal punctuation mark
53-
--> tests/ui/doc/doc_paragraphs_missing_punctuation.rs:90:47
47+
--> tests/ui/doc/doc_paragraphs_missing_punctuation.rs:83:47
5448
|
5549
LL | /// **But sometimes it is missing a period**
5650
| ^ help: end the paragraph with some punctuation: `.`
5751

5852
error: doc paragraphs should end with a terminal punctuation mark
59-
--> tests/ui/doc/doc_paragraphs_missing_punctuation.rs:95:46
53+
--> tests/ui/doc/doc_paragraphs_missing_punctuation.rs:88:46
6054
|
6155
LL | /// _But sometimes it is missing a period_
6256
| ^ help: end the paragraph with some punctuation: `.`
6357

6458
error: doc paragraphs should end with a terminal punctuation mark
65-
--> tests/ui/doc/doc_paragraphs_missing_punctuation.rs:104:56
59+
--> tests/ui/doc/doc_paragraphs_missing_punctuation.rs:97:56
6660
|
6761
LL | /// Doc comments can end with an [inline link](#anchor)
6862
| ^ help: end the paragraph with some punctuation: `.`
6963

7064
error: doc paragraphs should end with a terminal punctuation mark
71-
--> tests/ui/doc/doc_paragraphs_missing_punctuation.rs:108:65
65+
--> tests/ui/doc/doc_paragraphs_missing_punctuation.rs:101:65
7266
|
7367
LL | /// Some doc comments contain [link reference definitions][spec]
7468
| ^ help: end the paragraph with some punctuation: `.`
7569

7670
error: doc paragraphs should end with a terminal punctuation mark
77-
--> tests/ui/doc/doc_paragraphs_missing_punctuation.rs:133:57
71+
--> tests/ui/doc/doc_paragraphs_missing_punctuation.rs:144:57
7872
|
7973
LL | /// Doc comments with trailing blank lines are supported
8074
| ^ help: end the paragraph with some punctuation: `.`
8175

8276
error: doc paragraphs should end with a terminal punctuation mark
83-
--> tests/ui/doc/doc_paragraphs_missing_punctuation.rs:139:48
77+
--> tests/ui/doc/doc_paragraphs_missing_punctuation.rs:150:48
8478
|
8579
LL | /// This first paragraph is missing punctuation
8680
| ^ help: end the paragraph with some punctuation: `.`
8781

8882
error: doc paragraphs should end with a terminal punctuation mark
89-
--> tests/ui/doc/doc_paragraphs_missing_punctuation.rs:143:34
83+
--> tests/ui/doc/doc_paragraphs_missing_punctuation.rs:154:34
9084
|
9185
LL | /// And it has multiple sentences
9286
| ^ help: end the paragraph with some punctuation: `.`
9387

9488
error: doc paragraphs should end with a terminal punctuation mark
95-
--> tests/ui/doc/doc_paragraphs_missing_punctuation.rs:146:37
89+
--> tests/ui/doc/doc_paragraphs_missing_punctuation.rs:157:37
9690
|
9791
LL | /// Same for this third and last one
9892
| ^ help: end the paragraph with some punctuation: `.`
9993

10094
error: doc paragraphs should end with a terminal punctuation mark
101-
--> tests/ui/doc/doc_paragraphs_missing_punctuation.rs:153:33
95+
--> tests/ui/doc/doc_paragraphs_missing_punctuation.rs:164:33
10296
|
10397
LL | /// This ends with a code `span`
10498
| ^ help: end the paragraph with some punctuation: `.`
10599

106100
error: doc paragraphs should end with a terminal punctuation mark
107-
--> tests/ui/doc/doc_paragraphs_missing_punctuation.rs:162:27
101+
--> tests/ui/doc/doc_paragraphs_missing_punctuation.rs:173:27
108102
|
109103
LL | * Block doc comments work
110104
| ^ help: end the paragraph with some punctuation: `.`
111105

112-
error: aborting due to 18 previous errors
106+
error: aborting due to 17 previous errors
113107

0 commit comments

Comments
 (0)