From 2e6d11ea786cce95b718b73d07bc89a320d9ccbc Mon Sep 17 00:00:00 2001
From: Ilya Priven <ilya.konstantinov@gmail.com>
Date: Thu, 18 May 2023 04:34:15 -0400
Subject: [PATCH] Clarify difference between disallow_untyped_defs and
 disallow_incomplete_defs (#15247)

Fixes #9963, fixes #12693
---
 docs/source/command_line.rst | 9 +++++++--
 docs/source/config_file.rst  | 9 +++++++--
 mypy/main.py                 | 3 ++-
 3 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst
index 31d23db204eb..2809294092ab 100644
--- a/docs/source/command_line.rst
+++ b/docs/source/command_line.rst
@@ -353,12 +353,17 @@ definitions or calls.
 .. option:: --disallow-untyped-defs
 
     This flag reports an error whenever it encounters a function definition
-    without type annotations.
+    without type annotations or with incomplete type annotations.
+    (a superset of :option:`--disallow-incomplete-defs`).
+
+    For example, it would report an error for :code:`def f(a, b)` and :code:`def f(a: int, b)`.
 
 .. option:: --disallow-incomplete-defs
 
     This flag reports an error whenever it encounters a partly annotated
-    function definition.
+    function definition, while still allowing entirely unannotated definitions.
+
+    For example, it would report an error for :code:`def f(a: int, b)` but not :code:`def f(a, b)`.
 
 .. option:: --check-untyped-defs
 
diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst
index 9daaa7a4a5e5..b5ce1b0c1171 100644
--- a/docs/source/config_file.rst
+++ b/docs/source/config_file.rst
@@ -498,14 +498,19 @@ section of the command line docs.
     :default: False
 
     Disallows defining functions without type annotations or with incomplete type
-    annotations.
+    annotations (a superset of :confval:`disallow_incomplete_defs`).
+
+    For example, it would report an error for :code:`def f(a, b)` and :code:`def f(a: int, b)`.
 
 .. confval:: disallow_incomplete_defs
 
     :type: boolean
     :default: False
 
-    Disallows defining functions with incomplete type annotations.
+    Disallows defining functions with incomplete type annotations, while still
+    allowing entirely unannotated definitions.
+
+    For example, it would report an error for :code:`def f(a: int, b)` but not :code:`def f(a, b)`.
 
 .. confval:: check_untyped_defs
 
diff --git a/mypy/main.py b/mypy/main.py
index 943030f396c5..81a0a045745b 100644
--- a/mypy/main.py
+++ b/mypy/main.py
@@ -696,7 +696,8 @@ def add_invertible_flag(
         "--disallow-incomplete-defs",
         default=False,
         strict_flag=True,
-        help="Disallow defining functions with incomplete type annotations",
+        help="Disallow defining functions with incomplete type annotations "
+        "(while still allowing entirely unannotated definitions)",
         group=untyped_group,
     )
     add_invertible_flag(