Recategorize and document --warn-incomplete-stub (python#5555)

* Recategorize and document --warn-incomplete-stub

Previously, the `--warn-incomplete-stub` flag was inconsistently
documented: it was missing from the "Mypy command line" section of
the docs, but was documented in the "Mypy configuration file" section
and appeared under "Untyped definitions and calls" section when
running `mypy --help`.

This pull request:

1.  Adds documentation for this flag to the command line docs.

2.  Recategorizes the flag to fall under "Mypy internals" -- I
    can't really see people other then typeshed contributors
    finding this flag useful.

3.  Updates the docs so it states this flag is useful only when
    using `--disallow-incomplete-defs` or `--disallow-untyped-defs`
    instead of `--check-untyped-defs`. This option appears to be
    used [only once in checker.py][0] -- the `check_untyped_defs`
    option does not seem relevant there.

  [0]: https://github.com/python/mypy/blob/master/mypy/checker.py#L947

docs/source/command_line.rst

@@ -465,6 +465,21 @@ in developing or debugging mypy internals.
     submitting them upstream, but also allows you to use a forked version of
     typeshed.
 
+``--warn-incomplete-stub``
+    This flag modifies both the ``--disallow-untyped-defs`` and 
+    ``--disallow-incomplete-defs`` flags so they also report errors
+    if stubs in typeshed are missing type annotations or has incomplete
+    annotations. If both flags are missing, ``--warn-incomplete-stub``
+    also does nothing.
+
+    This flag is mainly intended to be used by people who want contribute
+    to typeshed and would like a convenient way to find gaps and omissions.
+
+    If you want mypy to report an error when your codebase *uses* an untyped
+    function, whether that function is defined in typeshed or not, use the 
+    ``--disallow-untyped-call`` flag. See :ref:`untyped-definitions-and-calls`
+    for more details.
+
 .. _shadow-file:
 
 ``--shadow-file SOURCE_FILE SHADOW_FILE``

docs/source/config_file.rst

@@ -103,7 +103,7 @@ The following global flags may only be set in the global section
 
 - ``warn_incomplete_stub`` (Boolean, default False) warns for missing
   type annotation in typeshed.  This is only relevant in combination
-  with ``check_untyped_defs``.
+  with ``disallow_untyped_defs`` or ``disallow_incomplete_defs``.
 
 - ``warn_redundant_casts`` (Boolean, default False) warns about
   casting an expression to its inferred type.

mypy/main.py

@@ -512,10 +512,6 @@ def add_invertible_flag(flag: str,
     add_invertible_flag('--check-untyped-defs', default=False, strict_flag=True,
                         help="Type check the interior of functions without type annotations",
                         group=untyped_group)
-    add_invertible_flag('--warn-incomplete-stub', default=False,
-                        help="Warn if missing type annotation in typeshed, only relevant with"
-                             " --check-untyped-defs enabled",
-                        group=untyped_group)
     add_invertible_flag('--disallow-untyped-decorators', default=False, strict_flag=True,
                         help="Disallow decorating typed functions with untyped decorators",
                         group=untyped_group)
@@ -608,6 +604,10 @@ def add_invertible_flag(flag: str,
     internals_group.add_argument(
         '--custom-typeshed-dir', metavar='DIR',
         help="Use the custom typeshed in DIR")
+    add_invertible_flag('--warn-incomplete-stub', default=False,
+                        help="Warn if missing type annotation in typeshed, only relevant with"
+                             " --disallow-untyped-defs or --disallow-incomplete-defs enabled",
+                        group=internals_group)
     internals_group.add_argument(
         '--shadow-file', nargs=2, metavar=('SOURCE_FILE', 'SHADOW_FILE'),
         dest='shadow_file', action='append',