Update docs on extra_checks flag (#18537)

Fixes #16189

Few things here:
* Soften a bit the language on the flag
* Delete docs for old deprecated `strict_concatenate` option that is now
part of `extra_checks`
* Add a bit more motivation to the flag description
* Update docs for `--strict` flag to mention `extra_checks` instead of
`strict_concatenate`

Note that the docs on config file option requested in the issue were
added a while ago.

docs/source/command_line.rst

@@ -692,9 +692,8 @@ of the above sections.
 .. option:: --extra-checks
 
     This flag enables additional checks that are technically correct but may be
-    impractical in real code. In particular, it prohibits partial overlap in
-    ``TypedDict`` updates, and makes arguments prepended via ``Concatenate``
-    positional-only. For example:
+    impractical. In particular, it prohibits partial overlap in ``TypedDict`` updates,
+    and makes arguments prepended via ``Concatenate`` positional-only. For example:
 
     .. code-block:: python
 
@@ -717,6 +716,13 @@ of the above sections.
        bad: Bad = {"a": 0, "b": "no"}
        test(bad, bar)
 
+    In future more checks may be added to this flag if:
+
+    * The corresponding use cases are rare, thus not justifying a dedicated
+      strictness flag.
+
+    * The new check cannot be supported as an opt-in error code.
+
 .. option:: --strict
 
     This flag mode enables all optional error checking flags.  You can see the

docs/source/config_file.rst

@@ -748,7 +748,7 @@ section of the command line docs.
    :type: boolean
    :default: False
 
-   This flag enables additional checks that are technically correct but may be impractical in real code.
+   This flag enables additional checks that are technically correct but may be impractical.
    See :option:`mypy --extra-checks` for more info.
 
 .. confval:: implicit_reexport
@@ -771,13 +771,6 @@ section of the command line docs.
        from foo import bar
        __all__ = ['bar']
 
-.. confval:: strict_concatenate
-
-   :type: boolean
-   :default: False
-
-   Make arguments prepended via ``Concatenate`` be truly positional-only.
-
 .. confval:: strict_equality
 
    :type: boolean

docs/source/existing_code.rst

@@ -199,9 +199,8 @@ The following config is equivalent to ``--strict`` (as of mypy 1.0):
    warn_redundant_casts = True
    warn_unused_ignores = True
 
-   # Getting these passing should be easy
+   # Getting this passing should be easy
    strict_equality = True
-   strict_concatenate = True
 
    # Strongly recommend enabling this one as soon as you can
    check_untyped_defs = True
@@ -223,6 +222,10 @@ The following config is equivalent to ``--strict`` (as of mypy 1.0):
    # This one can be tricky to get passing if you use a lot of untyped libraries
    warn_return_any = True
 
+   # This one is a catch-all flag for the rest of strict checks that are technically
+   # correct but may not be practical
+   extra_checks = True
+
 Note that you can also start with ``--strict`` and subtract, for instance:
 
 .. code-block:: text