diff --git a/CHANGELOG.md b/CHANGELOG.md index 2f8bf5e..ffa99cc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Change Log +## [0.1.8] - 2023-08-16 + +- Fixed + - Fixed a broken URL that used to point to `DOC103` notes + ([Issue #61](https://github.com/jsh9/pydoclint/issues/61)) +- Full diff + - https://github.com/jsh9/pydoclint/compare/0.1.7...0.1.8 + ## [0.1.7] - 2023-08-15 - Fixed diff --git a/docs/violation_codes.md b/docs/violation_codes.md index c4d10fa..08d3e85 100644 --- a/docs/violation_codes.md +++ b/docs/violation_codes.md @@ -6,6 +6,7 @@ - [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) @@ -23,21 +24,21 @@ ## 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://github.com/jsh9/pydoclint#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`:** +| 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: diff --git a/pydoclint/utils/violation.py b/pydoclint/utils/violation.py index 4b04315..b9401ea 100644 --- a/pydoclint/utils/violation.py +++ b/pydoclint/utils/violation.py @@ -11,7 +11,7 @@ 102: 'Docstring contains more arguments than in function signature.', 103: ( # noqa: PAR001 'Docstring arguments are different from function arguments.' - ' (Or could be other formatting issues: https://github.com/jsh9/pydoclint#notes-on-doc103 ).' + ' (Or could be other formatting issues: https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ).' ), 104: 'Arguments are the same in the docstring and the function signature, but are in a different order.', 105: 'Argument names match, but type hints do not match', diff --git a/setup.cfg b/setup.cfg index 9be6804..1b9a3d6 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,6 +1,6 @@ [metadata] name = pydoclint -version = 0.1.7 +version = 0.1.8 description = A Python docstring linter that checks arguments, returns, yields, and raises sections long_description = file: README.md long_description_content_type = text/markdown diff --git a/tests/test_main.py b/tests/test_main.py index 077f79e..dba3af5 100644 --- a/tests/test_main.py +++ b/tests/test_main.py @@ -18,7 +18,7 @@ 'but there are no type hints in the docstring arg list ', 'DOC103: Method `MyClass.func1_3`: Docstring arguments are different from ' 'function arguments. (Or could be other formatting issues: ' - 'https://github.com/jsh9/pydoclint#notes-on-doc103 ). Arguments in the function signature but not in ' + 'https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in ' 'the docstring: [arg1: str, arg2: list[int]].', 'DOC102: Method `MyClass.func1_6`: Docstring contains more arguments than in ' 'function signature. ', @@ -26,19 +26,19 @@ 'but there are no argument type hints in the signature ', 'DOC103: Method `MyClass.func1_6`: Docstring arguments are different from ' 'function arguments. (Or could be other formatting issues: ' - 'https://github.com/jsh9/pydoclint#notes-on-doc103 ). Arguments in the docstring but not in the ' + 'https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the docstring but not in the ' 'function signature: [arg1: int].', 'DOC101: Method `MyClass.func2`: Docstring contains fewer arguments than in ' 'function signature. ', 'DOC103: Method `MyClass.func2`: Docstring arguments are different from ' 'function arguments. (Or could be other formatting issues: ' - 'https://github.com/jsh9/pydoclint#notes-on-doc103 ). Arguments in the function signature but not in ' + 'https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in ' 'the docstring: [arg2: float | int | None].', 'DOC102: Method `MyClass.func3`: Docstring contains more arguments than in ' 'function signature. ', 'DOC103: Method `MyClass.func3`: Docstring arguments are different from ' 'function arguments. (Or could be other formatting issues: ' - 'https://github.com/jsh9/pydoclint#notes-on-doc103 ). Arguments in the docstring but not in the ' + 'https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the docstring but not in the ' 'function signature: [arg3: Optional[Union[float, int, str]]].', 'DOC104: Method `MyClass.func4`: Arguments are the same in the docstring and ' 'the function signature, but are in a different order. ', @@ -52,7 +52,7 @@ 'but there are no type hints in the docstring arg list ', 'DOC103: Function `func72`: Docstring arguments are different from function ' 'arguments. (Or could be other formatting issues: ' - 'https://github.com/jsh9/pydoclint#notes-on-doc103 ). Arguments in the function signature but not in the ' + 'https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the ' 'docstring: [arg3: list, arg4: tuple, arg5: dict].', ] @@ -63,7 +63,7 @@ 'but there are no type hints in the docstring arg list ', 'DOC103: Method `MyClass.func1_3`: Docstring arguments are different from ' 'function arguments. (Or could be other formatting issues: ' - 'https://github.com/jsh9/pydoclint#notes-on-doc103 ). Arguments in the function signature but not in ' + 'https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in ' 'the docstring: [arg1: str, arg2: list[int]].', 'DOC102: Method `MyClass.func1_6`: Docstring contains more arguments than in ' 'function signature. ', @@ -71,19 +71,19 @@ 'but there are no argument type hints in the signature ', 'DOC103: Method `MyClass.func1_6`: Docstring arguments are different from ' 'function arguments. (Or could be other formatting issues: ' - 'https://github.com/jsh9/pydoclint#notes-on-doc103 ). Arguments in the docstring but not in the ' + 'https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the docstring but not in the ' 'function signature: [arg1: int].', 'DOC101: Method `MyClass.func2`: Docstring contains fewer arguments than in ' 'function signature. ', 'DOC103: Method `MyClass.func2`: Docstring arguments are different from ' 'function arguments. (Or could be other formatting issues: ' - 'https://github.com/jsh9/pydoclint#notes-on-doc103 ). Arguments in the function signature but not in ' + 'https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in ' 'the docstring: [arg2: float | int | None].', 'DOC102: Method `MyClass.func3`: Docstring contains more arguments than in ' 'function signature. ', 'DOC103: Method `MyClass.func3`: Docstring arguments are different from ' 'function arguments. (Or could be other formatting issues: ' - 'https://github.com/jsh9/pydoclint#notes-on-doc103 ). Arguments in the docstring but not in the ' + 'https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the docstring but not in the ' 'function signature: [arg3: Optional[Union[float, int, str]]].', 'DOC105: Method `MyClass.func5`: Argument names match, but type hints do not ' 'match ', @@ -95,7 +95,7 @@ 'but there are no type hints in the docstring arg list ', 'DOC103: Function `func72`: Docstring arguments are different from function ' 'arguments. (Or could be other formatting issues: ' - 'https://github.com/jsh9/pydoclint#notes-on-doc103 ). Arguments in the function signature but not in the ' + 'https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the ' 'docstring: [arg3: list, arg4: tuple, arg5: dict].', ] @@ -162,7 +162,7 @@ def testReturns(style: str, filename: str) -> None: 'function signature. ', 'DOC103: Method `MyClass.func2`: Docstring arguments are different from ' 'function arguments. (Or could be other formatting issues: ' - 'https://github.com/jsh9/pydoclint#notes-on-doc103 ). Arguments in the function signature but not in ' + 'https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in ' 'the docstring: [arg2: float, arg3: str]. Arguments in the docstring but not ' 'in the function signature: [arg1: int].', 'DOC203: Method `MyClass.func2` return type(s) in docstring not consistent with the ' @@ -291,7 +291,7 @@ def _tweakViolationMsgForFunctions(expectedViolationsCopy: List[str]) -> None: 'but not all args in the signature have type hints ', 'DOC103: Function `func3`: Docstring arguments are different from function ' 'arguments. (Or could be other formatting issues: ' - 'https://github.com/jsh9/pydoclint#notes-on-doc103 ). Arguments in the function signature but not in the ' + 'https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the ' 'docstring: [arg1: , arg2: , arg3: ]. Arguments in the docstring but not in ' 'the function signature: [var1: int, var2: str].', ] @@ -307,7 +307,7 @@ def _tweakViolationMsgForFunctions(expectedViolationsCopy: List[str]) -> None: 'but there are no type hints in the docstring arg list ', 'DOC103: Function `func1`: Docstring arguments are different from function ' 'arguments. (Or could be other formatting issues: ' - 'https://github.com/jsh9/pydoclint#notes-on-doc103 ). Arguments in the ' + 'https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the ' 'function signature but not in the docstring: [arg1: , arg2: , arg3: ].', 'DOC201: Function `func1` does not have a return section in docstring ', 'DOC203: Function `func1` return type(s) in docstring not consistent with the ' @@ -323,7 +323,7 @@ def _tweakViolationMsgForFunctions(expectedViolationsCopy: List[str]) -> None: 'but there are no type hints in the docstring arg list ', 'DOC103: Function `func2`: Docstring arguments are different from function ' 'arguments. (Or could be other formatting issues: ' - 'https://github.com/jsh9/pydoclint#notes-on-doc103 ). Arguments in the ' + 'https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the ' 'function signature but not in the docstring: [arg1: , arg2: , arg3: ].', 'DOC201: Function `func2` does not have a return section in docstring ', 'DOC203: Function `func2` return type(s) in docstring not consistent with the ' @@ -337,7 +337,7 @@ def _tweakViolationMsgForFunctions(expectedViolationsCopy: List[str]) -> None: 'but not all args in the signature have type hints ', 'DOC103: Function `func3`: Docstring arguments are different from function ' 'arguments. (Or could be other formatting issues: ' - 'https://github.com/jsh9/pydoclint#notes-on-doc103 ). Arguments in the ' + 'https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the ' 'function signature but not in the docstring: [arg1: , arg2: , arg3: ]. ' 'Arguments in the docstring but not in the function signature: [var1: int, ' 'var2: str].', @@ -389,7 +389,7 @@ def testInit(style: str) -> None: 'because __init__() cannot return anything ', 'DOC103: Method `D.__init__`: Docstring arguments are different from function ' 'arguments. (Or could be other formatting issues: ' - 'https://github.com/jsh9/pydoclint#notes-on-doc103 ). Arguments in the function signature but not in the ' + 'https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the ' 'docstring: [arg1: int, arg2: float]. Arguments in the docstring but not in ' 'the function signature: [var1: list, var2: dict].', 'DOC302: Class `D`: The class docstring does not need a "Returns" section, ' @@ -521,27 +521,27 @@ def testStarsInArgumentList(style: str) -> None: 'but not all args in the docstring arg list have type hints ', 'DOC103: Function `func2`: Docstring arguments are different from function ' 'arguments. (Or could be other formatting issues: ' - 'https://github.com/jsh9/pydoclint#notes-on-doc103 ). Arguments in the function signature but not in the ' + 'https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the ' 'docstring: [**kwargs: ]. Arguments in the docstring but not in the function ' 'signature: [kwargs: ].', 'DOC110: Function `func4`: The option `--arg-type-hints-in-docstring` is `True` ' 'but not all args in the docstring arg list have type hints ', 'DOC103: Function `func4`: Docstring arguments are different from function ' 'arguments. (Or could be other formatting issues: ' - 'https://github.com/jsh9/pydoclint#notes-on-doc103 ). Arguments in the function signature but not in the ' + 'https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the ' 'docstring: [*args: ]. Arguments in the docstring but not in the function ' 'signature: [args: ].', 'DOC101: Function `func6`: Docstring contains fewer arguments than in ' 'function signature. ', 'DOC103: Function `func6`: Docstring arguments are different from function ' 'arguments. (Or could be other formatting issues: ' - 'https://github.com/jsh9/pydoclint#notes-on-doc103 ). Arguments in the function signature but not in the ' + 'https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the ' 'docstring: [**kwargs: , *args: ].', 'DOC101: Function `func7`: Docstring contains fewer arguments than in ' 'function signature. ', 'DOC103: Function `func7`: Docstring arguments are different from function ' 'arguments. (Or could be other formatting issues: ' - 'https://github.com/jsh9/pydoclint#notes-on-doc103 ). Arguments in the function signature but not in the ' + 'https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the ' 'docstring: [**kwargs: , *args: , arg1: float, arg2: str]. Arguments in the ' 'docstring but not in the function signature: [arg1: int, arg2: dict].', ]