implement requested changes, add required tests

Author: mpyuglgwkxcmodyrpo

docs/checking_class_attributes.md

@@ -190,10 +190,11 @@ class MyPet:
 
 ## 4. Inline docstrings
 
-PEP-257 indicates that string literals located directly after an assign
-statement may be treated as attribute documentation. As such, we also
-optionally support inline docstrings for class attributes with the
-`allow-inline-classvar-docs` option set to True (it is False by default).
+[PEP-257](https://peps.python.org/pep-0257/) indicates that string literals
+located directly after an assign statement may be treated as attribute
+documentation. As such, we also optionally support inline docstrings for class
+attributes with the `allow-inline-class-var-docs` option set to True (it is
+False by default).
 
 Attribute type documentation may be specified as the first thing in the
 docstring followed by a colon. For example:

docs/config_options.md

@@ -232,7 +232,7 @@ attributes, and all other attributes are treated as instance attributes.
 
 ## 19. `--allow-inline-classvar-docs` (shortform: `-aicvd`, default: `False`)
 
-If True, allow class attributes to have inline documentation. For example:
+If True, require class attributes to have inline documentation. For example:
 
 ```python
 class MyClass:
@@ -244,9 +244,10 @@ class MyClass:
 
 If False, pydoclint will not parse inline class attribute docstrings.
 
-Inline documentation will not supersede class-level documentation, meaning that
-if you declare an attribute at the class level **and** an inline docstring,
-pydoclint will take the class-level documentation and not the inline docstring.
+Inline documentation will not be allowed if this setting is set to False.
+Similarly, class-level documentation of class attributes will not be allowed if
+this option is set to True.
+
 Inline docstrings may specify the attribute type as the first token in the
 docstring followed by a `:`.
 

docs/notes_for_users.md

@@ -114,11 +114,9 @@ As mentioned in Section 2 above, _pydoclint_ uses static syntax analysis. As a
 result, it cannot really "know" that these type annotations are in fact
 equivalent:
 
-| Type annotation   | Equivalent version |
-| ----------------- | ------------------ |
-| `Optional[str]`   | `str \| None`      |
-| `Union[str, int]` | `int \| str`       |
-| `Tuple[str, int]` | `tuple[str, int]`  |
+| Type annotation | Equivalent version | | ----------------- |
+------------------ | | `Optional[str]` | `str \| None` | | `Union[str, int]` |
+`int \| str` | | `Tuple[str, int]` | `tuple[str, int]` |
 
 Additionally, _pydoclint_ does not recognize some docstring conventions allowed
 in the docstring style guide, such as using "`int, optional`" for

docs/style_mismatch.md

@@ -92,13 +92,12 @@ even when we fall back to the configured style the cost is still negligible.
 For reference, benchmarking large code bases (as of 2025/01/12) shows the
 overhead of style detection is only a few percent:
 
-|                              | numpy | scikit-learn | Bokeh | Airflow |
-| ---------------------------- | ----- | ------------ | ----- | ------- |
-| Number of .py files          | 581   | 929          | 1196  | 5004    |
-| Run time with 1 style [sec]  | 1.84  | 2.68         | 0.77  | 5.50    |
-| Run time with 3 styles [sec] | 1.91  | 2.79         | 0.78  | 5.77    |
-| Additional run time [sec]    | 0.07  | 0.11         | 0.01  | 0.07    |
-| Relative additional run time | 4%    | 4%           | 1%    | 5%      |
+| | numpy | scikit-learn | Bokeh | Airflow | | ---------------------------- |
+----- | ------------ | ----- | ------- | | Number of .py files | 581 | 929 |
+1196 | 5004 | | Run time with 1 style [sec] | 1.84 | 2.68 | 0.77 | 5.50 | | Run
+time with 3 styles [sec] | 1.91 | 2.79 | 0.78 | 5.77 | | Additional run time
+[sec] | 0.07 | 0.11 | 0.01 | 0.07 | | Relative additional run time | 4% | 4% |
+1% | 5% |
 
 ## 5. What violation code is associated with style mismatch?
 

docs/violation_codes.md

@@ -98,13 +98,15 @@ on the top) do not need to have a return section.
 
 ## 7. `DOC6xx`: Violations about class attributes
 
-| Code     | Explanation                                                                       |
-| -------- | --------------------------------------------------------------------------------- |
-| `DOC601` | Class docstring contains fewer class attributes than actual class attributes.     |
-| `DOC602` | Class docstring contains more class attributes than in actual class attributes.   |
-| `DOC603` | Class docstring attributes are different from actual class attributes.            |
-| `DOC604` | Attributes are the same in docstring and class def, but are in a different order. |
-| `DOC605` | Attribute names match, but type hints in these attributes do not match            |
+| Code     | Explanation                                                                                        |
+| -------- | -------------------------------------------------------------------------------------------------- |
+| `DOC601` | Class docstring contains fewer class attributes than actual class attributes.                      |
+| `DOC602` | Class docstring contains more class attributes than in actual class attributes.                    |
+| `DOC603` | Class docstring attributes are different from actual class attributes.                             |
+| `DOC604` | Attributes are the same in docstring and class def, but are in a different order.                  |
+| `DOC605` | Attribute names match, but type hints in these attributes do not match                             |
+| `DOC606` | Attribute should not have an inline docstring; please combine it with the docstring of the class   |
+| `DOC607` | The class docstring should not have an "Attributes" section; please document all attributes inline |
 
 More about checking class attributes:
 https://jsh9.github.io/pydoclint/checking_class_attributes.html

pydoclint/utils/arg.py

@@ -438,5 +438,8 @@ def insertAt(
             arg: Arg,
     ) -> None:
         """Insert an Arg at a specific index."""
+        if arg.name in self.lookup:
+            raise ValueError(f'Arg with name "{arg.name}" already exists.')
+
         self.infoList.insert(index, arg)
         self.lookup[arg.name] = arg.typeHint

pydoclint/utils/violation.py

@@ -21,33 +21,33 @@
         ' ).'
     ),
     104: (
-        'Arguments are the same in the docstring and the function signature,'
-        ' but are in a different order.'
+        'Arguments are the same in the docstring and the function'
+        ' signature, but are in a different order.'
     ),
-    105: 'Argument names match, but type hints in these args do not match:',
+    105: ('Argument names match, but type hints in these args do not match:'),
     106: (
-        'The option `--arg-type-hints-in-signature` is `True` but there are'
-        ' no argument type hints in the signature'
+        'The option `--arg-type-hints-in-signature` is `True` but'
+        ' there are no argument type hints in the signature'
     ),
     107: (
         'The option `--arg-type-hints-in-signature` is `True` but not all'
         ' args in the signature have type hints'
     ),
     108: (
-        'The option `--arg-type-hints-in-signature` is `False` but there are'
-        ' argument type hints in the signature'
+        'The option `--arg-type-hints-in-signature` is `False` but'
+        ' there are argument type hints in the signature'
     ),
     109: (
-        'The option `--arg-type-hints-in-docstring` is `True` but there are'
-        ' no type hints in the docstring arg list'
+        'The option `--arg-type-hints-in-docstring` is `True` but'
+        ' there are no type hints in the docstring arg list'
     ),
     110: (
         'The option `--arg-type-hints-in-docstring` is `True` but not all'
         ' args in the docstring arg list have type hints'
     ),
     111: (
-        'The option `--arg-type-hints-in-docstring` is `False` but there are'
-        ' type hints in the docstring arg list'
+        'The option `--arg-type-hints-in-docstring` is `False` but'
+        ' there are type hints in the docstring arg list'
     ),
     201: 'does not have a return section in docstring',
     202: (
@@ -59,20 +59,20 @@
         ' annotation.'
     ),
     301: (
-        '__init__() should not have a docstring; please combine it with the'
-        ' docstring of the class'
+        '__init__() should not have a docstring; please combine it'
+        ' with the docstring of the class'
     ),
     302: (
         'The class docstring does not need a "Returns" section, because'
         ' __init__() cannot return anything'
     ),
     303: (
-        'The __init__() docstring does not need a "Returns" section, because'
-        ' it cannot return anything'
+        'The __init__() docstring does not need a "Returns" section,'
+        ' because it cannot return anything'
     ),
     304: (
-        'Class docstring has an argument/parameter section; please put it in'
-        ' the __init__() docstring'
+        'Class docstring has an argument/parameter section; please'
+        ' put it in the __init__() docstring'
     ),
     305: (
         'Class docstring has a "Raises" section; please put it in the'
@@ -83,13 +83,13 @@
         ' __init__() cannot yield anything'
     ),
     307: (
-        'The __init__() docstring does not need a "Yields" section, because'
-        ' __init__() cannot yield anything'
+        'The __init__() docstring does not need a "Yields" section,'
+        ' because __init__() cannot yield anything'
     ),
     401: '',  # Deprecated
     402: (
-        'has "yield" statements, but the docstring does not have a "Yields"'
-        ' section'
+        'has "yield" statements, but the docstring does not have a'
+        ' "Yields" section'
     ),
     403: (
         'has a "Yields" section in the docstring, but there are no "yield"'
@@ -102,49 +102,58 @@
     ),
     405: (
         'has both "return" and "yield" statements. Please use'
-        ' Generator[YieldType, SendType, ReturnType] as the return type'
-        ' annotation, and put your yield type in YieldType and return type'
-        ' in ReturnType. More details in'
+        ' Generator[YieldType, SendType, ReturnType] as the'
+        ' return type annotation, and put your yield type in'
+        ' YieldType and return type in ReturnType. More details in'
         ' https://jsh9.github.io/pydoclint/notes_generator_vs_iterator.html'
     ),
     501: (
-        'has raise statements, but the docstring does not have a "Raises"'
-        ' section'
+        'has raise statements, but the docstring does not have a'
+        ' "Raises" section'
     ),
     502: (
-        'has a "Raises" section in the docstring, but there are not "raise"'
-        ' statements in the body'
+        'has a "Raises" section in the docstring, but there are not'
+        ' "raise" statements in the body'
     ),
     503: (
         'exceptions in the "Raises" section in the docstring do not match'
         ' those in the function body.'
     ),
     504: (
-        'has assert statements, but the docstring does not have a "Raises"'
-        ' section. (Assert statements could raise "AssertError".)'
+        'has assert statements, but the docstring does not have a'
+        ' "Raises" section. (Assert statements could raise'
+        ' "AssertError".)'
     ),
     601: (
-        'Class docstring contains fewer class attributes than actual class'
-        ' attributes.'
+        'Class docstring contains fewer class attributes than actual'
+        ' class attributes.'
     ),
     602: (
-        'Class docstring contains more class attributes than in actual class'
-        ' attributes.'
+        'Class docstring contains more class attributes than in actual'
+        ' class attributes.'
     ),
     603: (
         'Class docstring attributes are different from actual class'
         ' attributes.'
         ' (Or could be other formatting issues: '
-        'https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103'
-        ' ).'
+        'https://jsh9.github.io/pydoclint/violation_codes.html'
+        '#notes-on-doc103 ).'
     ),
     604: (
         'Attributes are the same in docstring and class def, but are in a'
         ' different order.'
     ),
     605: (
-        'Attribute names match, but type hints in these attributes do not'
-        ' match:'
+        'Attribute names match, but type hints in these'
+        ' attributes do not match:'
+    ),
+    606: (
+        'Attribute has an inline docstring, but should be documented in'
+        ' the class docstring instead.'
+    ),
+    607: (
+        'The class docstring does not need an "Attributes" section,'
+        ' because the class attributes are documented inline.'
     ),
 })