Upgrade the documentation, fix 'magic-value-comparison' doc (#7711)

4 files changed, 106 insertions, 6 deletions

diff --git a/doc/user_guide/checkers/extensions.rst b/doc/user_guide/checkers/extensions.rst
index d52c9c704..0e28d1d57 100644
--- a/doc/user_guide/checkers/extensions.rst
+++ b/doc/user_guide/checkers/extensions.rst
@@ -16,10 +16,12 @@ Pylint provides the following optional plugins:
 - :ref:`pylint.extensions.consider_ternary_expression`
 - :ref:`pylint.extensions.docparams`
 - :ref:`pylint.extensions.docstyle`
+- :ref:`pylint.extensions.dunder`
 - :ref:`pylint.extensions.empty_comment`
 - :ref:`pylint.extensions.emptystring`
 - :ref:`pylint.extensions.eq_without_hash`
 - :ref:`pylint.extensions.for_any_all`
+- :ref:`pylint.extensions.magic_value`
 - :ref:`pylint.extensions.mccabe`
 - :ref:`pylint.extensions.no_self_use`
 - :ref:`pylint.extensions.overlapping_exceptions`
@@ -79,6 +81,9 @@ Code Style checker Messages
   Emitted when an if assignment is directly followed by an if statement and
   both can be combined by using an assignment expression ``:=``. Requires
   Python 3.8 and ``py-version >= 3.8``.
+:consider-using-augmented-assign (R6104): *Use '%s' to do an augmented assign directly*
+  Emitted when an assignment is referring to the object that it is assigning
+  to. This can be changed to be an augmented assign. Disabled by default!
 
 
 .. _pylint.extensions.emptystring:
@@ -275,6 +280,23 @@ Docstyle checker Messages
   Used when a blank line is found at the beginning of a docstring.
 
 
+.. _pylint.extensions.dunder:
+
+Dunder checker
+~~~~~~~~~~~~~~
+
+This checker is provided by ``pylint.extensions.dunder``.
+Verbatim name of the checker is ``dunder``.
+
+See also :ref:`dunder checker's options' documentation <dunder-options>`
+
+Dunder checker Messages
+^^^^^^^^^^^^^^^^^^^^^^^
+:bad-dunder-name (W3201): *Bad or misspelled dunder method name %s.*
+  Used when a dunder method is misspelled or defined with a name not within the
+  predefined list of dunder names.
+
+
 .. _pylint.extensions.check_elif:
 
 Else If Used checker
@@ -335,6 +357,23 @@ Import-Private-Name checker Messages
   underscores should be considered private.
 
 
+.. _pylint.extensions.magic_value:
+
+Magic-Value checker
+~~~~~~~~~~~~~~~~~~~
+
+This checker is provided by ``pylint.extensions.magic_value``.
+Verbatim name of the checker is ``magic-value``.
+
+See also :ref:`magic-value checker's options' documentation <magic-value-options>`
+
+Magic-Value checker Messages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+:magic-value-comparison (R2004): *Consider using a named constant or an enum instead of '%s'.*
+  Using named constants instead of magic values helps improve readability and
+  maintainability of your code, try to avoid them in comparisons.
+
+
 .. _pylint.extensions.redefined_variable_type:
 
 Multiple Types checker
diff --git a/doc/user_guide/checkers/features.rst b/doc/user_guide/checkers/features.rst
index baaf5a1cd..f6616617c 100644
--- a/doc/user_guide/checkers/features.rst
+++ b/doc/user_guide/checkers/features.rst
@@ -876,9 +876,6 @@ Refactoring checker Messages
   Emitted when accessing only the first or last element of str.split(). The
   first and last element can be accessed by using str.split(sep, maxsplit=1)[0]
   or str.rsplit(sep, maxsplit=1)[-1] instead.
-:consider-using-augmented-assign (C0210): *Use '%s' to do an augmented assign directly*
-  Emitted when an assignment is referring to the object that it is assigning
-  to. This can be changed to be an augmented assign.
 :use-sequence-for-iteration (C0208): *Use a sequence type when iterating over values*
   When iterating over values, sequence types (e.g., ``lists``, ``tuples``,
   ``ranges``) are more efficient than ``sets``.
diff --git a/doc/user_guide/configuration/all-options.rst b/doc/user_guide/configuration/all-options.rst
index 41b58efba..0b38c0d2f 100644
--- a/doc/user_guide/configuration/all-options.rst
+++ b/doc/user_guide/configuration/all-options.rst
@@ -217,9 +217,9 @@ Standard Checkers
 
    confidence = ["HIGH", "CONTROL_FLOW", "INFERENCE", "INFERENCE_FAILURE", "UNDEFINED"]
 
-   # disable =
+   disable = ["consider-using-augmented-assign"]
 
-   # enable =
+   enable = []
 
    evaluation = "max(0, 0 if fatal else 10.0 - ((float(5 * error + warning + refactor + convention) / statement) * 10))"
 
@@ -1673,6 +1673,68 @@ Extensions
    </details>
 
 
+.. _dunder-options:
+
+``Dunder`` **Checker**
+----------------------
+--good-dunder-names
+"""""""""""""""""""
+*Good dunder names which should always be accepted.*
+
+**Default:**  ``[]``
+
+
+
+.. raw:: html
+
+   <details>
+   <summary><a>Example configuration section</a></summary>
+
+**Note:** Only ``tool.pylint`` is required, the section title is not. These are the default values.
+
+.. code-block:: toml
+
+   [tool.pylint.dunder]
+   good-dunder-names = []
+
+
+
+.. raw:: html
+
+   </details>
+
+
+.. _magic-value-options:
+
+``Magic-value`` **Checker**
+---------------------------
+--valid-magic-values
+""""""""""""""""""""
+* List of valid magic values that `magic-value-compare` will not detect.*
+
+**Default:**  ``(0, -1, 1, '', '__main__')``
+
+
+
+.. raw:: html
+
+   <details>
+   <summary><a>Example configuration section</a></summary>
+
+**Note:** Only ``tool.pylint`` is required, the section title is not. These are the default values.
+
+.. code-block:: toml
+
+   [tool.pylint.magic-value]
+   valid-magic-values = [0, -1, 1, "", "__main__"]
+
+
+
+.. raw:: html
+
+   </details>
+
+
 .. _parameter_documentation-options:
 
 ``Parameter_documentation`` **Checker**
diff --git a/doc/user_guide/messages/messages_overview.rst b/doc/user_guide/messages/messages_overview.rst
index c7720453f..0b96b275b 100644
--- a/doc/user_guide/messages/messages_overview.rst
+++ b/doc/user_guide/messages/messages_overview.rst
@@ -207,6 +207,7 @@ All messages in the warning category:
    warning/assert-on-tuple
    warning/attribute-defined-outside-init
    warning/bad-builtin
+   warning/bad-dunder-name
    warning/bad-format-string
    warning/bad-format-string-key
    warning/bad-indentation
@@ -382,7 +383,6 @@ All messages in the convention category:
    convention/compare-to-zero
    convention/consider-iterating-dictionary
    convention/consider-using-any-or-all
-   convention/consider-using-augmented-assign
    convention/consider-using-dict-items
    convention/consider-using-enumerate
    convention/consider-using-f-string
@@ -463,6 +463,7 @@ All messages in the refactor category:
    refactor/consider-swap-variables
    refactor/consider-using-alias
    refactor/consider-using-assignment-expr
+   refactor/consider-using-augmented-assign
    refactor/consider-using-dict-comprehension
    refactor/consider-using-from-import
    refactor/consider-using-generator
@@ -483,6 +484,7 @@ All messages in the refactor category:
    refactor/empty-comment
    refactor/inconsistent-return-statements
    refactor/literal-comparison
+   refactor/magic-value-comparison
    refactor/no-classmethod-decorator
    refactor/no-else-break
    refactor/no-else-continue