-
Notifications
You must be signed in to change notification settings - Fork 12
/
violation_codes.md
88 lines (67 loc) · 7.05 KB
/
violation_codes.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
# _pydoclint_ style violation codes
**Table of Contents**
<!--TOC-->
- [0. `DOC0xx`: Docstring parsing issues](#0-doc0xx-docstring-parsing-issues)
- [1. `DOC1xx`: Violations about input arguments](#1-doc1xx-violations-about-input-arguments)
- [Notes on `DOC103`](#notes-on-doc103)
- [2. `DOC2xx`: Violations about return argument(s)](#2-doc2xx-violations-about-return-arguments)
- [3. `DOC3xx`: Violations about class docstring and class constructor](#3-doc3xx-violations-about-class-docstring-and-class-constructor)
- [4. `DOC4xx`: Violations about "yield" statements](#4-doc4xx-violations-about-yield-statements)
- [5. `DOC5xx`: Violations about "raise" statements](#5-doc5xx-violations-about-raise-statements)
<!--TOC-->
---
## 0. `DOC0xx`: Docstring parsing issues
| Code | Explanation |
| -------- | ---------------------------------------- |
| `DOC001` | Potential formatting errors in docstring |
## 1. `DOC1xx`: Violations about input arguments
| Code | Explanation |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DOC101` | Docstring contains fewer arguments than in function signature |
| `DOC102` | Docstring contains more arguments than in function signature |
| `DOC103` | Docstring arguments are different from function arguments. (Or could be other formatting issues: https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103) |
| `DOC104` | Arguments are the same in the docstring and the function signature, but are in a different order. |
| `DOC105` | Argument names match, but type hints do not match |
| `DOC106` | The option `--arg-type-hints-in-signature` is `True` but there are no argument type hints in the signature |
| `DOC107` | The option `--arg-type-hints-in-signature` is `True` but not all args in the signature have type hints |
| `DOC108` | The option `--arg-type-hints-in-signature` is `False` but there are argument type hints in the signature |
| `DOC109` | The option `--arg-type-hints-in-docstring` is `True` but there are no type hints in the docstring arg list |
| `DOC110` | The option `--arg-type-hints-in-docstring` is `True` but not all args in the docstring arg list have type hints |
| `DOC111` | The option `--arg-type-hints-in-docstring` is `False` but there are type hints in the docstring arg list |
### Notes on `DOC103`
Other potential causes to `DOC103` include:
- Numpy docstring style requires this style: `arg1 : int` (a space between
`arg1` and `:`) but people sometimes write `arg1: int`. This will trigger
`DOC103`.
- In the Google style, writing an `Args:` section without the preceding summary
will also trigger `DOC103`.
## 2. `DOC2xx`: Violations about return argument(s)
| Code | Explanation |
| -------- | ---------------------------------------------------------------------------------------------------- |
| `DOC201` | Function/method does not have a return section in docstring |
| `DOC202` | Function/method has a return section in docstring, but there are no return statements or annotations |
| `DOC203` | Return type(s) in the docstring not consistent with the return annotation |
Note on `DOC201`: Methods with `@property` as its last decorator do not need to
have a return section.
## 3. `DOC3xx`: Violations about class docstring and class constructor
| Code | Explanation |
| -------- | ------------------------------------------------------------------------------------------------------- |
| `DOC301` | `__init__()` should not have a docstring; please combine it with the docstring of the class |
| `DOC302` | The class docstring does not need a "Returns" section, because `__init__()` cannot return anything |
| `DOC303` | The `__init__()` docstring does not need a "Returns" section, because it cannot return anything |
| `DOC304` | Class docstring has an argument/parameter section; please put it in the `__init__()` docstring |
| `DOC305` | Class docstring has a "Raises" section; please put it in the `__init__()` docstring |
| `DOC306` | The class docstring does not need a "Yields" section, because `__init__()` cannot yield anything |
| `DOC307` | The `__init__()` docstring does not need a "Yields" section, because `__init__()` cannot yield anything |
## 4. `DOC4xx`: Violations about "yield" statements
| Code | Explanation |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DOC401` | (Deprecated; this violation code no longer appears) |
| `DOC402` | Function/method has "yield" statements, but the docstring does not have a "Yields" section |
| `DOC403` | Function/method has a "Yields" section in the docstring, but there are no "yield" statements, or the return annotation is not a Generator/Iterator/Iterable |
| `DOC404` | The types in the docstring's Yields section and the return annotation in the signature are not consistent |
## 5. `DOC5xx`: Violations about "raise" statements
| Code | Explanation |
| -------- | --------------------------------------------------------------------------------------------------------- |
| `DOC501` | Function/method has "raise" statements, but the docstring does not have a "Raises" section |
| `DOC502` | Function/method has a "Raises" section in the docstring, but there are not "raise" statements in the body |