Duplicates (#10)

* add documentation and tests for duplicate args
* implement duplicate check for args
* add checks for duplicate attrs
* add check that exceptions are only described once
* increment version and add release

Author: jdkandersson

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [v1.1.0] - 2023-01-26
+
+### Added
+
+- Lint check that ensures all function/ method arguments are described only
+  once.
+- Lint check that ensures all class attributes are described only once.
+- Lint check that ensures all raised exceptions are described only once.
+
 ## [v1.0.4] - 2023-01-13
 
 ### Changed
@@ -93,3 +102,4 @@
 [v1.0.2]: https://github.com/jdkandersson/flake8-docstrings-complete/releases/v1.0.2
 [v1.0.3]: https://github.com/jdkandersson/flake8-docstrings-complete/releases/v1.0.3
 [v1.0.4]: https://github.com/jdkandersson/flake8-docstrings-complete/releases/v1.0.4
+[v1.1.0]: https://github.com/jdkandersson/flake8-docstrings-complete/releases/v1.1.0

README.md

@@ -57,18 +57,21 @@ def foo(bar, baz):
    in the argument section.
 3. If an arguments section is in the function/ method docstring, the argument
    section contains no arguments the function/ method doesn't have.
-4. If a function/ method has a return statement with a value, the return value
+4. Function/ method arguments are only documented once.
+5. If a function/ method has a return statement with a value, the return value
    section is included.
-5. If a function/ method has a yield statement with a value, the yield value
+6. If a function/ method has a yield statement with a value, the yield value
    section is included.
-6. If a function/ method raises an exception, the raises section is included
+7. If a function/ method raises an exception, the raises section is included
    with a description for each exception that is raised.
-7. If a class has public attributes, that the attributes section is included.
-8. If a class has public attributes, that all public attributes are in the
+8. Each raised exception is only described once.
+9. If a class has public attributes, that the attributes section is included.
+10. If a class has public attributes, that all public attributes are in the
    attributes section.
-9. If an attributes section is in the class docstring, the attributes section
+11. If an attributes section is in the class docstring, the attributes section
    contains no attributes the class doesn't have.
-10. Any of the sections being checked are not present multiple times.
+12. Class attributes are only documented once.
+13. Any of the sections being checked are not present multiple times.
 
 Note:
 
@@ -107,6 +110,8 @@ A few rules have been defined to allow for selective suppression:
   docstring.
 - `DCO024`: function/ method has one or more arguments described in the
   docstring which are not arguments of the function/ method.
+- `DCO025`: function/ method has one or more arguments described in the
+  docstring multiple times.
 - `DCO030`: function/ method that returns a value does not have the returns
   section in the docstring.
 - `DCO031`: function/ method that does not return a value has the returns
@@ -131,6 +136,8 @@ A few rules have been defined to allow for selective suppression:
   docstring which are not raised in the function/ method.
 - `DCO055`: function/ method that has a raise without an exception has an empty
   raises section in the docstring.
+- `DCO056`: function/ method has one or more exceptions described in the
+  docstring multiple times.
 - `DCO060`: class has one or more public attributes and the docstring does not
   have an attributes section.
 - `DCO061`: class with no attributes and the docstring has an attributes
@@ -141,6 +148,8 @@ A few rules have been defined to allow for selective suppression:
   docstring.
 - `DCO064`: class has one or more attributes described in the docstring which
   are not attributes of the class.
+- `DCO065`: class has one or more attributes described in the docstring
+  multiple times.
 
 ### Fix DCO010
 
@@ -446,6 +455,50 @@ class FooClass:
         """
 ```
 
+### Fix DCO025
+
+This linting rule is triggered by a function/ method that has one or more
+arguments and a docstring that describes one or more arguments where on or more
+of the described arguments are described multiple times. For example:
+
+```Python
+def foo(bar):
+    """Perform foo action.
+
+    Args:
+        bar: the value to perform the foo action on.
+        bar: the value to perform the foo action on.
+    """
+
+class FooClass:
+    def foo(self, bar):
+        """Perform foo action.
+
+        Args:
+            bar: the value to perform the foo action on.
+            bar: the value to perform the foo action on.
+        """
+```
+
+These examples can be fixed by removing the duplicate arguments from the docstring:
+
+```Python
+def foo(bar):
+    """Perform foo action.
+
+    Args:
+        bar: the value to perform the foo action on.
+    """
+
+class FooClass:
+    def foo(self, bar):
+        """Perform foo action.
+
+        Args:
+            bar: the value to perform the foo action on.
+        """
+```
+
 ### Fix DCO030
 
 This linting rule is triggered by a function/ method that has at least one
@@ -1121,6 +1174,55 @@ class FooClass:
             raise
 ```
 
+### Fix DCO056
+
+This linting rule is triggered by a function/ method that raises one or more
+exceptions and a docstring that describes one or more exceptions where on or
+more of the described exceptions are described multiple times. For example:
+
+```Python
+def foo():
+    """Perform foo action.
+
+    Raises:
+        BarError: the value to perform the foo action on was wrong.
+        BarError: the value to perform the foo action on was wrong.
+    """
+    raise BarError
+
+class FooClass:
+    def foo(self):
+        """Perform foo action.
+
+        Raises:
+            BarError: the value to perform the foo action on was wrong.
+            BarError: the value to perform the foo action on was wrong.
+        """
+        raise BarError
+```
+
+These examples can be fixed by removing the duplicate descriptions from the
+docstring:
+
+```Python
+def foo():
+    """Perform foo action.
+
+    Raises:
+        BarError: the value to perform the foo action on was wrong.
+    """
+    raise BarError
+
+class FooClass:
+    def foo(self):
+        """Perform foo action.
+
+        Raises:
+            BarError: the value to perform the foo action on was wrong.
+        """
+        raise BarError
+```
+
 ### Fix DCO060
 
 This linting rule is triggered by a class that has one or more public
@@ -1431,6 +1533,61 @@ class FooClass:
         self.bar = "bar"
 ```
 
+### Fix DCO065
+
+This linting rule is triggered by a class that has one or more attributes and a
+docstring that describes one or more attributes where on or more
+of the described attributes are described multiple times. For example:
+
+```Python
+class FooClass:
+    """Perform foo action.
+
+    Attrs:
+        bar: The value to perform the foo action on.
+        bar: The value to perform the foo action on.
+    """
+
+    bar = "bar"
+
+class FooClass:
+    """Perform foo action.
+
+    Attrs:
+        bar: The value to perform the foo action on.
+        bar: The value to perform the foo action on.
+    """
+
+    def __init__(self):
+        """Construct."""
+        self.bar = "bar"
+```
+
+These examples can be fixed by removing the duplicate descriptions from the
+docstring:
+
+```Python
+class FooClass:
+    """Perform foo action.
+
+    Attrs:
+        bar: The value to perform the foo action on.
+    """
+
+    bar = "bar"
+
+class FooClass:
+    """Perform foo action.
+
+    Attrs:
+        bar: The value to perform the foo action on.
+    """
+
+    def __init__(self):
+        """Construct."""
+        self.bar = "bar"
+```
+
 ## Docstring Examples
 
 Examples of function/ method and class docstrings are:

flake8_docstrings_complete/args.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import ast
+from collections import Counter
 from typing import Iterator
 
 from . import docstring, types_
@@ -35,6 +36,11 @@
     f'{ARG_IN_DOCSTR_CODE} "%s" argument should not be described in the docstring{MORE_INFO_BASE}'
     f"{ARG_IN_DOCSTR_CODE.lower()}"
 )
+DUPLICATE_ARG_CODE = f"{ERROR_CODE_PREFIX}025"
+DUPLICATE_ARG_MSG = (
+    f'{DUPLICATE_ARG_CODE} "%s" argument documented multiple times{MORE_INFO_BASE}'
+    f"{DUPLICATE_ARG_CODE.lower()}"
+)
 
 SKIP_ARGS = {"self", "cls"}
 UNUSED_ARGS_PREFIX = "_"
@@ -91,7 +97,9 @@ def check(
         yield types_.Problem(
             docstr_node.lineno, docstr_node.col_offset, ARGS_SECTION_IN_DOCSTR_MSG
         )
-    elif all_args and docstr_info.args is not None:
+
+    # Checks for function with arguments and args section
+    if all_args and docstr_info.args is not None:
         docstr_args = set(docstr_info.args)
 
         # Check for multiple args sections
@@ -116,6 +124,14 @@ def check(
             for arg in sorted(docstr_args - func_args)
         )
 
+        # Check for duplicate arguments
+        arg_occurrences = Counter(docstr_info.args)
+        yield from (
+            types_.Problem(docstr_node.lineno, docstr_node.col_offset, DUPLICATE_ARG_MSG % arg)
+            for arg, occurrences in arg_occurrences.items()
+            if occurrences > 1
+        )
+
         # Check for empty args section
         if not all_used_args and len(docstr_info.args) == 0:
             yield types_.Problem(

flake8_docstrings_complete/attrs.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import ast
+from collections import Counter
 from itertools import chain
 from typing import Iterable, Iterator
 
@@ -34,6 +35,11 @@
     f'{ATTR_IN_DOCSTR_CODE} "%s" attribute should not be described in the docstring'
     f"{MORE_INFO_BASE}{ATTR_IN_DOCSTR_CODE.lower()}"
 )
+DUPLICATE_ATTR_CODE = f"{ERROR_CODE_PREFIX}065"
+DUPLICATE_ATTR_MSG = (
+    f'{DUPLICATE_ATTR_CODE} "%s" attribute documented multiple times{MORE_INFO_BASE}'
+    f"{DUPLICATE_ATTR_CODE.lower()}"
+)
 
 CLASS_SELF_CLS = {"self", "cls"}
 PRIVATE_ATTR_PREFIX = "_"
@@ -186,12 +192,15 @@ def check(
         yield types_.Problem(
             docstr_node.lineno, docstr_node.col_offset, ATTRS_SECTION_NOT_IN_DOCSTR_MSG
         )
+
     # Check that attrs section is not in docstring if class has no attributes
     if not all_targets and docstr_info.attrs is not None:
         yield types_.Problem(
             docstr_node.lineno, docstr_node.col_offset, ATTRS_SECTION_IN_DOCSTR_MSG
         )
-    elif all_targets and docstr_info.attrs is not None:
+
+    # Checks for class with attributes and an attrs section
+    if all_targets and docstr_info.attrs is not None:
         docstr_attrs = set(docstr_info.attrs)
 
         # Check for multiple attrs sections
@@ -216,6 +225,14 @@ def check(
             for attr in sorted(docstr_attrs - class_attrs)
         )
 
+        # Check for duplicate attributes
+        attr_occurrences = Counter(docstr_info.attrs)
+        yield from (
+            types_.Problem(docstr_node.lineno, docstr_node.col_offset, DUPLICATE_ATTR_MSG % attr)
+            for attr, occurrences in attr_occurrences.items()
+            if occurrences > 1
+        )
+
         # Check for empty attrs section
         if not all_public_class_targets and len(docstr_info.attrs) == 0:
             yield types_.Problem(

flake8_docstrings_complete/raises.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import ast
+from collections import Counter
 from typing import Iterable, Iterator
 
 from . import docstring, types_
@@ -42,6 +43,11 @@
     "describe at least one exception in the raises section of the docstring"
     f"{MORE_INFO_BASE}{RE_RAISE_NO_EXC_IN_DOCSTR_CODE.lower()}"
 )
+DUPLICATE_EXC_CODE = f"{ERROR_CODE_PREFIX}056"
+DUPLICATE_EXC_MSG = (
+    f'{DUPLICATE_EXC_CODE} "%s" exception documented multiple times{MORE_INFO_BASE}'
+    f"{DUPLICATE_EXC_CODE.lower()}"
+)
 
 
 def _get_exc_node(node: ast.Raise) -> types_.Node | None:
@@ -116,7 +122,9 @@ def check(
         yield types_.Problem(
             docstr_node.lineno, docstr_node.col_offset, RE_RAISE_NO_EXC_IN_DOCSTR_MSG
         )
-    elif all_excs and docstr_info.raises is not None:
+
+    # Checks for exceptions raised and raises section in docstring
+    if all_excs and docstr_info.raises is not None:
         docstr_raises = set(docstr_info.raises)
 
         # Check for multiple raises sections
@@ -134,6 +142,14 @@ def check(
             if exc and exc.name not in docstr_raises
         )
 
+        # Check for duplicate exceptions in raises
+        exc_occurrences = Counter(docstr_info.raises)
+        yield from (
+            types_.Problem(docstr_node.lineno, docstr_node.col_offset, DUPLICATE_EXC_MSG % exc)
+            for exc, occurrences in exc_occurrences.items()
+            if occurrences > 1
+        )
+
         # Check for exceptions in the docstring that are not raised unless function has a raises
         # without an exception
         if not has_raise_no_value:

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "flake8-docstrings-complete"
-version = "1.0.4"
+version = "1.1.0"
 description = "A linter that checks docstrings are complete"
 authors = ["David Andersson <[email protected]>"]
 license = "Apache 2.0"