Cyclic0007/ruff
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[pydoclint] Update diagnostics to target the docstring (#14381)

Browse Source 
## Summary

Updates the `pydoclint` diagnostics to target the docstring instead of a
related statement.

Closes #13184

## Test Plan

`cargo nextest run`
This commit is contained in:
Tom Kuson
2024-11-16 18:32:20 +00:00
committed by GitHub
parent 78210b198b
commit d0dca7bfcf
13 changed files with 765 additions and 324 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
crates/ruff_linter/src/rules/pydoclint/rules/check_docstring.rs
View File

@@ -878,7 +878,7 @@ pub(crate) fn check_docstring(
{
let extra_property_decorators = checker.settings.pydocstyle.property_decorators();
if !definition.is_property(extra_property_decorators, semantic) {
if let Some(body_return) = body_entries.returns.first() {
if body_entries.returns.first().is_some() {
match function_def.returns.as_deref() {
Some(returns) => {
// Ignore it if it's annotated as returning `None`
@@ -893,7 +893,7 @@ pub(crate) fn check_docstring(
{
diagnostics.push(Diagnostic::new(
DocstringMissingReturns,
body_return.range(),
docstring.range(),
));
}
}
@@ -902,10 +902,8 @@ pub(crate) fn check_docstring(
.iter()
.any(|entry| !entry.is_none_return()) =>
{
diagnostics.push(Diagnostic::new(
DocstringMissingReturns,
body_return.range(),
));
diagnostics
.push(Diagnostic::new(DocstringMissingReturns, docstring.range()));
}
_ => {}
}
@@ -917,7 +915,7 @@ pub(crate) fn check_docstring(
// DOC402
if checker.enabled(Rule::DocstringMissingYields) {
if !yields_documented(docstring, &docstring_sections, convention) {
if let Some(body_yield) = body_entries.yields.first() {
if body_entries.yields.first().is_some() {
match function_def.returns.as_deref() {
Some(returns)
if !generator_annotation_arguments(returns, semantic).is_some_and(
@@ -925,11 +923,11 @@ pub(crate) fn check_docstring(
) =>
{
diagnostics
.push(Diagnostic::new(DocstringMissingYields, body_yield.range()));
.push(Diagnostic::new(DocstringMissingYields, docstring.range()));
}
None if body_entries.yields.iter().any(|entry| !entry.is_none_yield) => {
diagnostics
.push(Diagnostic::new(DocstringMissingYields, body_yield.range()));
.push(Diagnostic::new(DocstringMissingYields, docstring.range()));
}
_ => {}
}
@@ -960,7 +958,7 @@ pub(crate) fn check_docstring(
DocstringMissingException {
id: (*name).to_string(),
},
body_raise.range(),
docstring.range(),
);
diagnostics.push(diagnostic);
}
@@ -972,12 +970,11 @@ pub(crate) fn check_docstring(
if !visibility::is_abstract(&function_def.decorator_list, semantic) {
// DOC202
if checker.enabled(Rule::DocstringExtraneousReturns) {
if let Some(ref docstring_returns) = docstring_sections.returns {
if docstring_sections.returns.is_some() {
if body_entries.returns.is_empty()
|| body_entries.returns.iter().all(ReturnEntry::is_implicit)
{
let diagnostic =
Diagnostic::new(DocstringExtraneousReturns, docstring_returns.range());
let diagnostic = Diagnostic::new(DocstringExtraneousReturns, docstring.range());
diagnostics.push(diagnostic);
}
}
@@ -985,10 +982,9 @@ pub(crate) fn check_docstring(
// DOC403
if checker.enabled(Rule::DocstringExtraneousYields) {
if let Some(docstring_yields) = docstring_sections.yields {
if docstring_sections.yields.is_some() {
if body_entries.yields.is_empty() {
let diagnostic =
Diagnostic::new(DocstringExtraneousYields, docstring_yields.range());
let diagnostic = Diagnostic::new(DocstringExtraneousYields, docstring.range());
diagnostics.push(diagnostic);
}
}
@@ -1013,7 +1009,7 @@ pub(crate) fn check_docstring(
DocstringExtraneousException {
ids: extraneous_exceptions,
},
docstring_raises.range(),
docstring.range(),
);
diagnostics.push(diagnostic);
}

60
crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-extraneous-exception_DOC502_google.py.snap
View File

@@ -2,40 +2,70 @@
source: crates/ruff_linter/src/rules/pydoclint/mod.rs
snapshot_kind: text
---
DOC502_google.py:16:1: DOC502 Raised exception is not explicitly raised: `FasterThanLightError`
DOC502_google.py:7:5: DOC502 Raised exception is not explicitly raised: `FasterThanLightError`
|
14 | Speed as distance divided by time.
15 |
16 | / Raises:
5 | # DOC502
6 | def calculate_speed(distance: float, time: float) -> float:
7 | """Calculate speed as distance divided by time.
| _____^
8 | |
9 | | Args:
10 | | distance: Distance traveled.
11 | | time: Time spent traveling.
12 | |
13 | | Returns:
14 | | Speed as distance divided by time.
15 | |
16 | | Raises:
17 | | FasterThanLightError: If speed is greater than the speed of light.
18 | | """
| |____^ DOC502
| |_______^ DOC502
19 | return distance / time
|
= help: Remove `FasterThanLightError` from the docstring
DOC502_google.py:33:1: DOC502 Raised exceptions are not explicitly raised: `FasterThanLightError`, `DivisionByZero`
DOC502_google.py:24:5: DOC502 Raised exceptions are not explicitly raised: `FasterThanLightError`, `DivisionByZero`
|
31 | Speed as distance divided by time.
32 |
33 | / Raises:
22 | # DOC502
23 | def calculate_speed(distance: float, time: float) -> float:
24 | """Calculate speed as distance divided by time.
| _____^
25 | |
26 | | Args:
27 | | distance: Distance traveled.
28 | | time: Time spent traveling.
29 | |
30 | | Returns:
31 | | Speed as distance divided by time.
32 | |
33 | | Raises:
34 | | FasterThanLightError: If speed is greater than the speed of light.
35 | | DivisionByZero: Divide by zero.
36 | | """
| |____^ DOC502
| |_______^ DOC502
37 | return distance / time
|
= help: Remove `FasterThanLightError`, `DivisionByZero` from the docstring
DOC502_google.py:51:1: DOC502 Raised exception is not explicitly raised: `DivisionByZero`
DOC502_google.py:42:5: DOC502 Raised exception is not explicitly raised: `DivisionByZero`
|
49 | Speed as distance divided by time.
50 |
51 | / Raises:
40 | # DOC502
41 | def calculate_speed(distance: float, time: float) -> float:
42 | """Calculate speed as distance divided by time.
| _____^
43 | |
44 | | Args:
45 | | distance: Distance traveled.
46 | | time: Time spent traveling.
47 | |
48 | | Returns:
49 | | Speed as distance divided by time.
50 | |
51 | | Raises:
52 | | FasterThanLightError: If speed is greater than the speed of light.
53 | | DivisionByZero: Divide by zero.
54 | | """
| |____^ DOC502
| |_______^ DOC502
55 | try:
56 | return distance / time
|

78
crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-extraneous-exception_DOC502_numpy.py.snap
View File

@@ -2,48 +2,96 @@
source: crates/ruff_linter/src/rules/pydoclint/mod.rs
snapshot_kind: text
---
DOC502_numpy.py:22:1: DOC502 Raised exception is not explicitly raised: `FasterThanLightError`
DOC502_numpy.py:7:5: DOC502 Raised exception is not explicitly raised: `FasterThanLightError`
|
20 | Speed as distance divided by time.
21 |
22 | / Raises
5 | # DOC502
6 | def calculate_speed(distance: float, time: float) -> float:
7 | """
| _____^
8 | | Calculate speed as distance divided by time.
9 | |
10 | | Parameters
11 | | ----------
12 | | distance : float
13 | | Distance traveled.
14 | | time : float
15 | | Time spent traveling.
16 | |
17 | | Returns
18 | | -------
19 | | float
20 | | Speed as distance divided by time.
21 | |
22 | | Raises
23 | | ------
24 | | FasterThanLightError
25 | | If speed is greater than the speed of light.
26 | | """
| |____^ DOC502
| |_______^ DOC502
27 | return distance / time
|
= help: Remove `FasterThanLightError` from the docstring
DOC502_numpy.py:47:1: DOC502 Raised exceptions are not explicitly raised: `FasterThanLightError`, `DivisionByZero`
DOC502_numpy.py:32:5: DOC502 Raised exceptions are not explicitly raised: `FasterThanLightError`, `DivisionByZero`
|
45 | Speed as distance divided by time.
46 |
47 | / Raises
30 | # DOC502
31 | def calculate_speed(distance: float, time: float) -> float:
32 | """
| _____^
33 | | Calculate speed as distance divided by time.
34 | |
35 | | Parameters
36 | | ----------
37 | | distance : float
38 | | Distance traveled.
39 | | time : float
40 | | Time spent traveling.
41 | |
42 | | Returns
43 | | -------
44 | | float
45 | | Speed as distance divided by time.
46 | |
47 | | Raises
48 | | ------
49 | | FasterThanLightError
50 | | If speed is greater than the speed of light.
51 | | DivisionByZero
52 | | If attempting to divide by zero.
53 | | """
| |____^ DOC502
| |_______^ DOC502
54 | return distance / time
|
= help: Remove `FasterThanLightError`, `DivisionByZero` from the docstring
DOC502_numpy.py:74:1: DOC502 Raised exception is not explicitly raised: `DivisionByZero`
DOC502_numpy.py:59:5: DOC502 Raised exception is not explicitly raised: `DivisionByZero`
|
72 | Speed as distance divided by time.
73 |
74 | / Raises
57 | # DOC502
58 | def calculate_speed(distance: float, time: float) -> float:
59 | """
| _____^
60 | | Calculate speed as distance divided by time.
61 | |
62 | | Parameters
63 | | ----------
64 | | distance : float
65 | | Distance traveled.
66 | | time : float
67 | | Time spent traveling.
68 | |
69 | | Returns
70 | | -------
71 | | float
72 | | Speed as distance divided by time.
73 | |
74 | | Raises
75 | | ------
76 | | FasterThanLightError
77 | | If speed is greater than the speed of light.
78 | | DivisionByZero
79 | | If attempting to divide by zero.
80 | | """
| |____^ DOC502
| |_______^ DOC502
81 | try:
82 | return distance / time
|

45
crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-extraneous-returns_DOC202_google.py.snap
View File

@@ -2,38 +2,55 @@
source: crates/ruff_linter/src/rules/pydoclint/mod.rs
snapshot_kind: text
---
DOC202_google.py:20:1: DOC202 Docstring should not have a returns section because the function doesn't return anything
DOC202_google.py:14:5: DOC202 Docstring should not have a returns section because the function doesn't return anything
|
18 | num (int): A number
19 |
20 | / Returns:
12 | # DOC202
13 | def foo(num: int) -> str:
14 | """
| _____^
15 | | Do something
16 | |
17 | | Args:
18 | | num (int): A number
19 | |
20 | | Returns:
21 | | str: A string
22 | | """
| |____^ DOC202
| |_______^ DOC202
23 | print('test')
|
= help: Remove the "Returns" section
DOC202_google.py:36:1: DOC202 Docstring should not have a returns section because the function doesn't return anything
DOC202_google.py:30:9: DOC202 Docstring should not have a returns section because the function doesn't return anything
|
34 | num (int): A number
35 |
36 | / Returns:
28 | # DOC202
29 | def foo(self) -> str:
30 | """
| _________^
31 | | Do something
32 | |
33 | | Args:
34 | | num (int): A number
35 | |
36 | | Returns:
37 | | str: A string
38 | | """
| |________^ DOC202
| |___________^ DOC202
39 | print('test')
|
= help: Remove the "Returns" section
DOC202_google.py:82:1: DOC202 Docstring should not have a returns section because the function doesn't return anything
DOC202_google.py:80:5: DOC202 Docstring should not have a returns section because the function doesn't return anything
|
78 | # DOC202 -- never explicitly returns anything, just short-circuits
79 | def foo(s: str, condition: bool):
80 | """Fooey things.
81 |
82 | / Returns:
| _____^
81 | |
82 | | Returns:
83 | | None
84 | | """
| |____^ DOC202
| |_______^ DOC202
85 | if not condition:
86 | return
|

38
crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-extraneous-returns_DOC202_numpy.py.snap
View File

@@ -2,30 +2,48 @@
source: crates/ruff_linter/src/rules/pydoclint/mod.rs
snapshot_kind: text
---
DOC202_numpy.py:24:1: DOC202 Docstring should not have a returns section because the function doesn't return anything
DOC202_numpy.py:16:5: DOC202 Docstring should not have a returns section because the function doesn't return anything
|
22 | A number
23 |
24 | / Returns
14 | # DOC202
15 | def foo(num: int) -> str:
16 | """
| _____^
17 | | Do something
18 | |
19 | | Parameters
20 | | ----------
21 | | num : int
22 | | A number
23 | |
24 | | Returns
25 | | -------
26 | | str
27 | | A string
28 | | """
| |____^ DOC202
| |_______^ DOC202
29 | print('test')
|
= help: Remove the "Returns" section
DOC202_numpy.py:44:1: DOC202 Docstring should not have a returns section because the function doesn't return anything
DOC202_numpy.py:36:9: DOC202 Docstring should not have a returns section because the function doesn't return anything
|
42 | A number
43 |
44 | / Returns
34 | # DOC202
35 | def foo(self) -> str:
36 | """
| _________^
37 | | Do something
38 | |
39 | | Parameters
40 | | ----------
41 | | num : int
42 | | A number
43 | |
44 | | Returns
45 | | -------
46 | | str
47 | | A string
48 | | """
| |________^ DOC202
| |___________^ DOC202
49 | print('test')
|
= help: Remove the "Returns" section

34
crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-extraneous-yields_DOC403_google.py.snap
View File

@@ -2,26 +2,40 @@
source: crates/ruff_linter/src/rules/pydoclint/mod.rs
snapshot_kind: text
---
DOC403_google.py:20:1: DOC403 Docstring has a "Yields" section but the function doesn't yield anything
DOC403_google.py:14:5: DOC403 Docstring has a "Yields" section but the function doesn't yield anything
|
18 | num (int): A number
19 |
20 | / Yields:
12 | # DOC403
13 | def foo(num: int) -> str:
14 | """
| _____^
15 | | Do something
16 | |
17 | | Args:
18 | | num (int): A number
19 | |
20 | | Yields:
21 | | str: A string
22 | | """
| |____^ DOC403
| |_______^ DOC403
23 | print('test')
|
= help: Remove the "Yields" section
DOC403_google.py:36:1: DOC403 Docstring has a "Yields" section but the function doesn't yield anything
DOC403_google.py:30:9: DOC403 Docstring has a "Yields" section but the function doesn't yield anything
|
34 | num (int): A number
35 |
36 | / Yields:
28 | # DOC403
29 | def foo(self) -> str:
30 | """
| _________^
31 | | Do something
32 | |
33 | | Args:
34 | | num (int): A number
35 | |
36 | | Yields:
37 | | str: A string
38 | | """
| |________^ DOC403
| |___________^ DOC403
39 | print('test')
|
= help: Remove the "Yields" section

38
crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-extraneous-yields_DOC403_numpy.py.snap
View File

@@ -2,30 +2,48 @@
source: crates/ruff_linter/src/rules/pydoclint/mod.rs
snapshot_kind: text
---
DOC403_numpy.py:24:1: DOC403 Docstring has a "Yields" section but the function doesn't yield anything
DOC403_numpy.py:16:5: DOC403 Docstring has a "Yields" section but the function doesn't yield anything
|
22 | A number
23 |
24 | / Yields
14 | # DOC403
15 | def foo(num: int) -> str:
16 | """
| _____^
17 | | Do something
18 | |
19 | | Parameters
20 | | ----------
21 | | num : int
22 | | A number
23 | |
24 | | Yields
25 | | -------
26 | | str
27 | | A string
28 | | """
| |____^ DOC403
| |_______^ DOC403
29 | print('test')
|
= help: Remove the "Yields" section
DOC403_numpy.py:44:1: DOC403 Docstring has a "Yields" section but the function doesn't yield anything
DOC403_numpy.py:36:9: DOC403 Docstring has a "Yields" section but the function doesn't yield anything
|
42 | A number
43 |
44 | / Yields
34 | # DOC403
35 | def foo(self) -> str:
36 | """
| _________^
37 | | Do something
38 | |
39 | | Parameters
40 | | ----------
41 | | num : int
42 | | A number
43 | |
44 | | Yields
45 | | -------
46 | | str
47 | | A string
48 | | """
| |________^ DOC403
| |___________^ DOC403
49 | print('test')
|
= help: Remove the "Yields" section

190
crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-missing-exception_DOC501_google.py.snap
View File

@@ -2,90 +2,168 @@
source: crates/ruff_linter/src/rules/pydoclint/mod.rs
snapshot_kind: text
---
DOC501_google.py:46:15: DOC501 Raised exception `FasterThanLightError` missing from docstring
DOC501_google.py:34:5: DOC501 Raised exception `FasterThanLightError` missing from docstring
|
44 | return distance / time
45 | except ZeroDivisionError as exc:
46 | raise FasterThanLightError from exc
| ^^^^^^^^^^^^^^^^^^^^ DOC501
32 | # DOC501
33 | def calculate_speed(distance: float, time: float) -> float:
34 | """Calculate speed as distance divided by time.
| _____^
35 | |
36 | | Args:
37 | | distance: Distance traveled.
38 | | time: Time spent traveling.
39 | |
40 | | Returns:
41 | | Speed as distance divided by time.
42 | | """
| |_______^ DOC501
43 | try:
44 | return distance / time
|
= help: Add `FasterThanLightError` to the docstring
DOC501_google.py:63:15: DOC501 Raised exception `FasterThanLightError` missing from docstring
DOC501_google.py:51:5: DOC501 Raised exception `ValueError` missing from docstring
|
61 | return distance / time
62 | except ZeroDivisionError as exc:
63 | raise FasterThanLightError from exc
| ^^^^^^^^^^^^^^^^^^^^ DOC501
64 | except:
65 | raise ValueError
|
= help: Add `FasterThanLightError` to the docstring
DOC501_google.py:65:15: DOC501 Raised exception `ValueError` missing from docstring
|
63 | raise FasterThanLightError from exc
64 | except:
65 | raise ValueError
| ^^^^^^^^^^ DOC501
49 | # DOC501
50 | def calculate_speed(distance: float, time: float) -> float:
51 | """Calculate speed as distance divided by time.
| _____^
52 | |
53 | | Args:
54 | | distance: Distance traveled.
55 | | time: Time spent traveling.
56 | |
57 | | Returns:
58 | | Speed as distance divided by time.
59 | | """
| |_______^ DOC501
60 | try:
61 | return distance / time
|
= help: Add `ValueError` to the docstring
DOC501_google.py:115:11: DOC501 Raised exception `AnotherError` missing from docstring
DOC501_google.py:51:5: DOC501 Raised exception `FasterThanLightError` missing from docstring
|
49 | # DOC501
50 | def calculate_speed(distance: float, time: float) -> float:
51 | """Calculate speed as distance divided by time.
| _____^
52 | |
53 | | Args:
54 | | distance: Distance traveled.
55 | | time: Time spent traveling.
56 | |
57 | | Returns:
58 | | Speed as distance divided by time.
59 | | """
| |_______^ DOC501
60 | try:
61 | return distance / time
|
= help: Add `FasterThanLightError` to the docstring
DOC501_google.py:106:5: DOC501 Raised exception `AnotherError` missing from docstring
|
113 | Speed as distance divided by time.
114 | """
115 | raise AnotherError
| ^^^^^^^^^^^^ DOC501
104 | # DOC501
105 | def calculate_speed(distance: float, time: float) -> float:
106 | """Calculate speed as distance divided by time.
| _____^
107 | |
108 | | Args:
109 | | distance: Distance traveled.
110 | | time: Time spent traveling.
111 | |
112 | | Returns:
113 | | Speed as distance divided by time.
114 | | """
| |_______^ DOC501
115 | raise AnotherError
|
= help: Add `AnotherError` to the docstring
DOC501_google.py:129:11: DOC501 Raised exception `AnotherError` missing from docstring
DOC501_google.py:120:5: DOC501 Raised exception `AnotherError` missing from docstring
|
127 | Speed as distance divided by time.
128 | """
129 | raise AnotherError()
| ^^^^^^^^^^^^^^ DOC501
118 | # DOC501
119 | def calculate_speed(distance: float, time: float) -> float:
120 | """Calculate speed as distance divided by time.
| _____^
121 | |
122 | | Args:
123 | | distance: Distance traveled.
124 | | time: Time spent traveling.
125 | |
126 | | Returns:
127 | | Speed as distance divided by time.
128 | | """
| |_______^ DOC501
129 | raise AnotherError()
|
= help: Add `AnotherError` to the docstring
DOC501_google.py:139:11: DOC501 Raised exception `SomeError` missing from docstring
DOC501_google.py:134:5: DOC501 Raised exception `SomeError` missing from docstring
|
137 | bar: Bar.
138 | """
139 | raise something.SomeError
| ^^^^^^^^^^^^^^^^^^^ DOC501
132 | # DOC501
133 | def foo(bar: int):
134 | """Foo.
| _____^
135 | |
136 | | Args:
137 | | bar: Bar.
138 | | """
| |_______^ DOC501
139 | raise something.SomeError
|
= help: Add `SomeError` to the docstring
DOC501_google.py:213:9: DOC501 Raised exception `ZeroDivisionError` missing from docstring
DOC501_google.py:197:5: DOC501 Raised exception `ZeroDivisionError` missing from docstring
|
211 | except ZeroDivisionError:
212 | print("Oh no, why would you divide something by zero?")
213 | raise
| ^^^^^ DOC501
214 | except TypeError:
215 | print("Not a number? Shame on you!")
195 | # DOC501
196 | def calculate_speed(distance: float, time: float) -> float:
197 | """Calculate speed as distance divided by time.
| _____^
198 | |
199 | | Args:
200 | | distance: Distance traveled.
201 | | time: Time spent traveling.
202 | |
203 | | Returns:
204 | | Speed as distance divided by time.
205 | |
206 | | Raises:
207 | | TypeError: if you didn't pass a number for both parameters
208 | | """
| |_______^ DOC501
209 | try:
210 | return distance / time
|
= help: Add `ZeroDivisionError` to the docstring
DOC501_google.py:244:15: DOC501 Raised exception `TypeError` missing from docstring
DOC501_google.py:238:5: DOC501 Raised exception `TypeError` missing from docstring
|
242 | """
243 | if True:
244 | raise TypeError # DOC501
| ^^^^^^^^^ DOC501
245 | else:
246 | raise TypeError # no DOC501 here because we already emitted a diagnostic for the earlier `raise TypeError`
237 | def foo():
238 | """Foo.
| _____^
239 | |
240 | | Returns:
241 | | 42: int.
242 | | """
| |_______^ DOC501
243 | if True:
244 | raise TypeError # DOC501
|
= help: Add `TypeError` to the docstring
DOC501_google.py:247:11: DOC501 Raised exception `ValueError` missing from docstring
DOC501_google.py:238:5: DOC501 Raised exception `ValueError` missing from docstring
|
245 | else:
246 | raise TypeError # no DOC501 here because we already emitted a diagnostic for the earlier `raise TypeError`
247 | raise ValueError # DOC501
| ^^^^^^^^^^ DOC501
248 | return 42
237 | def foo():
238 | """Foo.
| _____^
239 | |
240 | | Returns:
241 | | 42: int.
242 | | """
| |_______^ DOC501
243 | if True:
244 | raise TypeError # DOC501
|
= help: Add `ValueError` to the docstring

163
crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-missing-exception_DOC501_numpy.py.snap
View File

@@ -2,61 +2,146 @@
source: crates/ruff_linter/src/rules/pydoclint/mod.rs
snapshot_kind: text
---
DOC501_numpy.py:53:15: DOC501 Raised exception `FasterThanLightError` missing from docstring
DOC501_numpy.py:35:5: DOC501 Raised exception `FasterThanLightError` missing from docstring
|
51 | return distance / time
52 | except ZeroDivisionError as exc:
53 | raise FasterThanLightError from exc
| ^^^^^^^^^^^^^^^^^^^^ DOC501
33 | # DOC501
34 | def calculate_speed(distance: float, time: float) -> float:
35 | """
| _____^
36 | | Calculate speed as distance divided by time.
37 | |
38 | | Parameters
39 | | ----------
40 | | distance : float
41 | | Distance traveled.
42 | | time : float
43 | | Time spent traveling.
44 | |
45 | | Returns
46 | | -------
47 | | float
48 | | Speed as distance divided by time.
49 | | """
| |_______^ DOC501
50 | try:
51 | return distance / time
|
= help: Add `FasterThanLightError` to the docstring
DOC501_numpy.py:76:15: DOC501 Raised exception `FasterThanLightError` missing from docstring
DOC501_numpy.py:58:5: DOC501 Raised exception `ValueError` missing from docstring
|
74 | return distance / time
75 | except ZeroDivisionError as exc:
76 | raise FasterThanLightError from exc
| ^^^^^^^^^^^^^^^^^^^^ DOC501
77 | except:
78 | raise ValueError
|
= help: Add `FasterThanLightError` to the docstring
DOC501_numpy.py:78:15: DOC501 Raised exception `ValueError` missing from docstring
|
76 | raise FasterThanLightError from exc
77 | except:
78 | raise ValueError
| ^^^^^^^^^^ DOC501
56 | # DOC501
57 | def calculate_speed(distance: float, time: float) -> float:
58 | """
| _____^
59 | | Calculate speed as distance divided by time.
60 | |
61 | | Parameters
62 | | ----------
63 | | distance : float
64 | | Distance traveled.
65 | | time : float
66 | | Time spent traveling.
67 | |
68 | | Returns
69 | | -------
70 | | float
71 | | Speed as distance divided by time.
72 | | """
| |_______^ DOC501
73 | try:
74 | return distance / time
|
= help: Add `ValueError` to the docstring
DOC501_numpy.py:111:9: DOC501 Raised exception `TypeError` missing from docstring
DOC501_numpy.py:58:5: DOC501 Raised exception `FasterThanLightError` missing from docstring
|
56 | # DOC501
57 | def calculate_speed(distance: float, time: float) -> float:
58 | """
| _____^
59 | | Calculate speed as distance divided by time.
60 | |
61 | | Parameters
62 | | ----------
63 | | distance : float
64 | | Distance traveled.
65 | | time : float
66 | | Time spent traveling.
67 | |
68 | | Returns
69 | | -------
70 | | float
71 | | Speed as distance divided by time.
72 | | """
| |_______^ DOC501
73 | try:
74 | return distance / time
|
= help: Add `FasterThanLightError` to the docstring
DOC501_numpy.py:83:5: DOC501 Raised exception `TypeError` missing from docstring
|
109 | except TypeError:
110 | print("Not a number? Shame on you!")
111 | raise
| ^^^^^ DOC501
81 | # DOC501
82 | def calculate_speed(distance: float, time: float) -> float:
83 | """Calculate speed as distance divided by time.
| _____^
84 | |
85 | | ACalculate speed as distance divided by time.
86 | |
87 | | Parameters
88 | | ----------
89 | | distance : float
90 | | Distance traveled.
91 | | time : float
92 | | Time spent traveling.
93 | |
94 | | Returns
95 | | -------
96 | | float
97 | | Speed as distance divided by time.
98 | |
99 | | Raises
100 | | ------
101 | | ZeroDivisionError
102 | | If attempting to divide by zero.
103 | | """
| |_______^ DOC501
104 | try:
105 | return distance / time
|
= help: Add `TypeError` to the docstring
DOC501_numpy.py:147:15: DOC501 Raised exception `TypeError` missing from docstring
DOC501_numpy.py:139:5: DOC501 Raised exception `TypeError` missing from docstring
|
145 | """
146 | if True:
147 | raise TypeError # DOC501
| ^^^^^^^^^ DOC501
148 | else:
149 | raise TypeError # no DOC501 here because we already emitted a diagnostic for the earlier `raise TypeError`
138 | def foo():
139 | """Foo.
| _____^
140 | |
141 | | Returns
142 | | -------
143 | | int
144 | | 42
145 | | """
| |_______^ DOC501
146 | if True:
147 | raise TypeError # DOC501
|
= help: Add `TypeError` to the docstring
DOC501_numpy.py:150:11: DOC501 Raised exception `ValueError` missing from docstring
DOC501_numpy.py:139:5: DOC501 Raised exception `ValueError` missing from docstring
|
148 | else:
149 | raise TypeError # no DOC501 here because we already emitted a diagnostic for the earlier `raise TypeError`
150 | raise ValueError # DOC501
| ^^^^^^^^^^ DOC501
151 | return 42
138 | def foo():
139 | """Foo.
| _____^
140 | |
141 | | Returns
142 | | -------
143 | | int
144 | | 42
145 | | """
| |_______^ DOC501
146 | if True:
147 | raise TypeError # DOC501
|
= help: Add `ValueError` to the docstring

100
crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-missing-returns_DOC201_google.py.snap
View File

@@ -2,71 +2,101 @@
source: crates/ruff_linter/src/rules/pydoclint/mod.rs
snapshot_kind: text
---
DOC201_google.py:9:5: DOC201 `return` is not documented in docstring
DOC201_google.py:3:5: DOC201 `return` is not documented in docstring
|
7 | num (int): A number
8 | """
9 | return 'test'
| ^^^^^^^^^^^^^ DOC201
1 | # DOC201
2 | def foo(num: int) -> str:
3 | """
| _____^
4 | | Do something
5 | |
6 | | Args:
7 | | num (int): A number
8 | | """
| |_______^ DOC201
9 | return 'test'
|
= help: Add a "Returns" section to the docstring
DOC201_google.py:50:9: DOC201 `return` is not documented in docstring
DOC201_google.py:44:9: DOC201 `return` is not documented in docstring
|
48 | num (int): A number
49 | """
50 | return 'test'
| ^^^^^^^^^^^^^ DOC201
42 | # DOC201
43 | def bar(self) -> str:
44 | """
| _________^
45 | | Do something
46 | |
47 | | Args:
48 | | num (int): A number
49 | | """
| |___________^ DOC201
50 | return 'test'
|
= help: Add a "Returns" section to the docstring
DOC201_google.py:71:9: DOC201 `return` is not documented in docstring
DOC201_google.py:70:9: DOC201 `return` is not documented in docstring
|
68 | # DOC201
69 | def nested():
70 | """Do something nested."""
| ^^^^^^^^^^^^^^^^^^^^^^^^^^ DOC201
71 | return 5
| ^^^^^^^^ DOC201
72 |
73 | print("I never return")
|
= help: Add a "Returns" section to the docstring
DOC201_google.py:121:9: DOC201 `return` is not documented in docstring
DOC201_google.py:120:9: DOC201 `return` is not documented in docstring
|
118 | @abc.abstractmethod
119 | def f(self):
120 | """Lorem ipsum."""
| ^^^^^^^^^^^^^^^^^^ DOC201
121 | return True
| ^^^^^^^^^^^ DOC201
|
= help: Add a "Returns" section to the docstring
DOC201_google.py:184:9: DOC201 `return` is not documented in docstring
DOC201_google.py:178:5: DOC201 `return` is not documented in docstring
|
182 | """
183 | if x < 0:
184 | return None
| ^^^^^^^^^^^ DOC201
185 | else:
186 | return x
176 | # DOC201 - non-early return explicit None
177 | def foo(x: int) -> int | None:
178 | """A very helpful docstring.
| _____^
179 | |
180 | | Args:
181 | | x (int): An interger.
182 | | """
| |_______^ DOC201
183 | if x < 0:
184 | return None
|
= help: Add a "Returns" section to the docstring
DOC201_google.py:197:9: DOC201 `return` is not documented in docstring
DOC201_google.py:191:5: DOC201 `return` is not documented in docstring
|
195 | """
196 | if x < 0:
197 | return None
| ^^^^^^^^^^^ DOC201
198 | else:
199 | return x
189 | # DOC201 - non-early return explicit None w/o useful type annotations
190 | def foo(x):
191 | """A very helpful docstring.
| _____^
192 | |
193 | | Args:
194 | | x (int): An interger.
195 | | """
| |_______^ DOC201
196 | if x < 0:
197 | return None
|
= help: Add a "Returns" section to the docstring
DOC201_google.py:209:5: DOC201 `return` is not documented in docstring
DOC201_google.py:204:5: DOC201 `return` is not documented in docstring
|
207 | s (str): A string.
208 | """
209 | return None
| ^^^^^^^^^^^ DOC201
202 | # DOC201 - only returns None, but return annotation is not None
203 | def foo(s: str) -> str | None:
204 | """A very helpful docstring.
| _____^
205 | |
206 | | Args:
207 | | s (str): A string.
208 | | """
| |_______^ DOC201
209 | return None
|
= help: Add a "Returns" section to the docstring

125
crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-missing-returns_DOC201_numpy.py.snap
View File

@@ -2,96 +2,143 @@
source: crates/ruff_linter/src/rules/pydoclint/mod.rs
snapshot_kind: text
---
DOC201_numpy.py:11:5: DOC201 `return` is not documented in docstring
DOC201_numpy.py:3:5: DOC201 `return` is not documented in docstring
|
9 | A number
10 | """
11 | return 'test'
| ^^^^^^^^^^^^^ DOC201
1 | # DOC201
2 | def foo(num: int) -> str:
3 | """
| _____^
4 | | Do something
5 | |
6 | | Parameters
7 | | ----------
8 | | num : int
9 | | A number
10 | | """
| |_______^ DOC201
11 | return 'test'
|
= help: Add a "Returns" section to the docstring
DOC201_numpy.py:62:9: DOC201 `return` is not documented in docstring
DOC201_numpy.py:54:9: DOC201 `return` is not documented in docstring
|
60 | A number
61 | """
62 | return 'test'
| ^^^^^^^^^^^^^ DOC201
52 | # DOC201
53 | def bar(self) -> str:
54 | """
| _________^
55 | | Do something
56 | |
57 | | Parameters
58 | | ----------
59 | | num : int
60 | | A number
61 | | """
| |___________^ DOC201
62 | return 'test'
|
= help: Add a "Returns" section to the docstring
DOC201_numpy.py:87:9: DOC201 `return` is not documented in docstring
DOC201_numpy.py:86:9: DOC201 `return` is not documented in docstring
|
84 | @abc.abstractmethod
85 | def f(self):
86 | """Lorem ipsum."""
| ^^^^^^^^^^^^^^^^^^ DOC201
87 | return True
| ^^^^^^^^^^^ DOC201
|
= help: Add a "Returns" section to the docstring
DOC201_numpy.py:160:9: DOC201 `return` is not documented in docstring
DOC201_numpy.py:152:5: DOC201 `return` is not documented in docstring
|
158 | """
159 | if x < 0:
160 | return None
| ^^^^^^^^^^^ DOC201
161 | else:
162 | return x
150 | # DOC201 - non-early return explicit None
151 | def foo(x: int) -> int | None:
152 | """A very helpful docstring.
| _____^
153 | |
154 | | Parameters
155 | | ----------
156 | | x : int
157 | | An interger.
158 | | """
| |_______^ DOC201
159 | if x < 0:
160 | return None
|
= help: Add a "Returns" section to the docstring
DOC201_numpy.py:175:9: DOC201 `return` is not documented in docstring
DOC201_numpy.py:167:5: DOC201 `return` is not documented in docstring
|
173 | """
174 | if x < 0:
175 | return None
| ^^^^^^^^^^^ DOC201
176 | else:
177 | return x
165 | # DOC201 - non-early return explicit None w/o useful type annotations
166 | def foo(x):
167 | """A very helpful docstring.
| _____^
168 | |
169 | | Parameters
170 | | ----------
171 | | x : int
172 | | An interger.
173 | | """
| |_______^ DOC201
174 | if x < 0:
175 | return None
|
= help: Add a "Returns" section to the docstring
DOC201_numpy.py:189:5: DOC201 `return` is not documented in docstring
DOC201_numpy.py:182:5: DOC201 `return` is not documented in docstring
|
187 | A string.
188 | """
189 | return None
| ^^^^^^^^^^^ DOC201
180 | # DOC201 - only returns None, but return annotation is not None
181 | def foo(s: str) -> str | None:
182 | """A very helpful docstring.
| _____^
183 | |
184 | | Parameters
185 | | ----------
186 | | x : str
187 | | A string.
188 | | """
| |_______^ DOC201
189 | return None
|
= help: Add a "Returns" section to the docstring
DOC201_numpy.py:195:5: DOC201 `return` is not documented in docstring
DOC201_numpy.py:194:5: DOC201 `return` is not documented in docstring
|
192 | # DOC201
193 | def bar() -> int | None:
194 | """Bar-y method"""
| ^^^^^^^^^^^^^^^^^^ DOC201
195 | return
| ^^^^^^ DOC201
|
= help: Add a "Returns" section to the docstring
DOC201_numpy.py:222:5: DOC201 `return` is not documented in docstring
DOC201_numpy.py:220:5: DOC201 `return` is not documented in docstring
|
218 | # indicates it could sometimes return `int`
219 | def generator_function_3() -> Generator[str, None, int | None]:
220 | """Generate some strings"""
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^ DOC201
221 | yield from "abc"
222 | return
| ^^^^^^ DOC201
|
= help: Add a "Returns" section to the docstring
DOC201_numpy.py:230:5: DOC201 `return` is not documented in docstring
DOC201_numpy.py:228:5: DOC201 `return` is not documented in docstring
|
226 | # indicates it could sometimes return `int`
227 | def generator_function_4():
228 | """Generate some strings"""
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^ DOC201
229 | yield from "abc"
230 | return 42
| ^^^^^^^^^ DOC201
|
= help: Add a "Returns" section to the docstring
DOC201_numpy.py:236:5: DOC201 `return` is not documented in docstring
DOC201_numpy.py:235:5: DOC201 `return` is not documented in docstring
|
233 | # DOC201 -- no `yield` expressions, so not a generator function
234 | def not_a_generator() -> Iterator[int]:
235 | """"No returns documented here, oh no"""
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ DOC201
236 | return (x for x in range(42))
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ DOC201
|
= help: Add a "Returns" section to the docstring

74
crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-missing-yields_DOC402_google.py.snap
View File

@@ -2,58 +2,80 @@
source: crates/ruff_linter/src/rules/pydoclint/mod.rs
snapshot_kind: text
---
DOC402_google.py:9:5: DOC402 `yield` is not documented in docstring
DOC402_google.py:3:5: DOC402 `yield` is not documented in docstring
|
7 | num (int): A number
8 | """
9 | yield 'test'
| ^^^^^^^^^^^^ DOC402
1 | # DOC402
2 | def foo(num: int) -> str:
3 | """
| _____^
4 | | Do something
5 | |
6 | | Args:
7 | | num (int): A number
8 | | """
| |_______^ DOC402
9 | yield 'test'
|
= help: Add a "Yields" section to the docstring
DOC402_google.py:50:9: DOC402 `yield` is not documented in docstring
DOC402_google.py:44:9: DOC402 `yield` is not documented in docstring
|
48 | num (int): A number
49 | """
50 | yield 'test'
| ^^^^^^^^^^^^ DOC402
42 | # DOC402
43 | def bar(self) -> str:
44 | """
| _________^
45 | | Do something
46 | |
47 | | Args:
48 | | num (int): A number
49 | | """
| |___________^ DOC402
50 | yield 'test'
|
= help: Add a "Yields" section to the docstring
DOC402_google.py:59:9: DOC402 `yield` is not documented in docstring
DOC402_google.py:58:9: DOC402 `yield` is not documented in docstring
|
56 | # DOC402
57 | def nested():
58 | """Do something nested."""
| ^^^^^^^^^^^^^^^^^^^^^^^^^^ DOC402
59 | yield 5
| ^^^^^^^ DOC402
60 |
61 | print("I never yield")
|
= help: Add a "Yields" section to the docstring
DOC402_google.py:67:5: DOC402 `yield` is not documented in docstring
DOC402_google.py:66:5: DOC402 `yield` is not documented in docstring
|
64 | # DOC402
65 | def test():
66 | """Do something."""
| ^^^^^^^^^^^^^^^^^^^ DOC402
67 | yield from range(10)
| ^^^^^^^^^^^^^^^^^^^^ DOC402
|
= help: Add a "Yields" section to the docstring
DOC402_google.py:100:5: DOC402 `yield` is not documented in docstring
DOC402_google.py:97:5: DOC402 `yield` is not documented in docstring
|
98 | Do something
99 | """
100 | yield
| ^^^^^ DOC402
95 | # DOC402
96 | def foo() -> collections.abc.Generator[int | None, None, None]:
97 | """
| _____^
98 | | Do something
99 | | """
| |_______^ DOC402
100 | yield
|
= help: Add a "Yields" section to the docstring
DOC402_google.py:108:5: DOC402 `yield` is not documented in docstring
DOC402_google.py:105:5: DOC402 `yield` is not documented in docstring
|
106 | Do something
107 | """
108 | yield
| ^^^^^ DOC402
103 | # DOC402
104 | def bar() -> collections.abc.Iterator[int | None]:
105 | """
| _____^
106 | | Do something
107 | | """
| |_______^ DOC402
108 | yield
|
= help: Add a "Yields" section to the docstring

114
crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-missing-yields_DOC402_numpy.py.snap
View File

@@ -2,68 +2,106 @@
source: crates/ruff_linter/src/rules/pydoclint/mod.rs
snapshot_kind: text
---
DOC402_numpy.py:11:5: DOC402 `yield` is not documented in docstring
DOC402_numpy.py:3:5: DOC402 `yield` is not documented in docstring
|
9 | A number
10 | """
11 | yield 'test'
| ^^^^^^^^^^^^ DOC402
1 | # DOC402
2 | def foo(num: int) -> str:
3 | """
| _____^
4 | | Do something
5 | |
6 | | Parameters
7 | | ----------
8 | | num : int
9 | | A number
10 | | """
| |_______^ DOC402
11 | yield 'test'
|
= help: Add a "Yields" section to the docstring
DOC402_numpy.py:62:9: DOC402 `yield` is not documented in docstring
DOC402_numpy.py:54:9: DOC402 `yield` is not documented in docstring
|
60 | A number
61 | """
62 | yield 'test'
| ^^^^^^^^^^^^ DOC402
52 | # DOC402
53 | def bar(self) -> str:
54 | """
| _________^
55 | | Do something
56 | |
57 | | Parameters
58 | | ----------
59 | | num : int
60 | | A number
61 | | """
| |___________^ DOC402
62 | yield 'test'
|
= help: Add a "Yields" section to the docstring
DOC402_numpy.py:89:5: DOC402 `yield` is not documented in docstring
DOC402_numpy.py:86:5: DOC402 `yield` is not documented in docstring
|
87 | Do something
88 | """
89 | yield None
| ^^^^^^^^^^ DOC402
90 | yield 1
84 | # DOC402
85 | def foo() -> typing.Generator[int | None, None, None]:
86 | """
| _____^
87 | | Do something
88 | | """
| |_______^ DOC402
89 | yield None
90 | yield 1
|
= help: Add a "Yields" section to the docstring
DOC402_numpy.py:98:5: DOC402 `yield` is not documented in docstring
DOC402_numpy.py:95:5: DOC402 `yield` is not documented in docstring
|
96 | Do something
97 | """
98 | yield None
| ^^^^^^^^^^ DOC402
93 | # DOC402
94 | def foo() -> typing.Generator[int, None, None]:
95 | """
| _____^
96 | | Do something
97 | | """
| |_______^ DOC402
98 | yield None
|
= help: Add a "Yields" section to the docstring
DOC402_numpy.py:122:5: DOC402 `yield` is not documented in docstring
DOC402_numpy.py:119:5: DOC402 `yield` is not documented in docstring
|
120 | Do something
121 | """
122 | yield None
| ^^^^^^^^^^ DOC402
123 | yield 1
117 | # DOC402
118 | def foo():
119 | """
| _____^
120 | | Do something
121 | | """
| |_______^ DOC402
122 | yield None
123 | yield 1
|
= help: Add a "Yields" section to the docstring
DOC402_numpy.py:131:5: DOC402 `yield` is not documented in docstring
DOC402_numpy.py:128:5: DOC402 `yield` is not documented in docstring
|
129 | Do something
130 | """
131 | yield 1
| ^^^^^^^ DOC402
132 | yield
126 | # DOC402
127 | def foo():
128 | """
| _____^
129 | | Do something
130 | | """
| |_______^ DOC402
131 | yield 1
132 | yield
|
= help: Add a "Yields" section to the docstring
DOC402_numpy.py:140:5: DOC402 `yield` is not documented in docstring
DOC402_numpy.py:137:5: DOC402 `yield` is not documented in docstring
|
138 | Do something
139 | """
140 | yield
| ^^^^^ DOC402
135 | # DOC402
136 | def bar() -> typing.Iterator[int | None]:
137 | """
| _____^
138 | | Do something
139 | | """
| |_______^ DOC402
140 | yield
|
= help: Add a "Yields" section to the docstring