update documentation

Author: wyattscarpenter

docs/source/command_line.rst

@@ -85,8 +85,9 @@ for full details, see :ref:`running-mypy`.
 
     This flag will add everything that matches ``.gitignore`` file(s) to :option:`--exclude`.
 
+.. _optional-arguments:
 
-Optional arguments
+Utility arguments
 ******************
 
 .. option:: -h, --help
@@ -1035,6 +1036,70 @@ in developing or debugging mypy internals.
     cause mypy to type check the contents of ``temp.py`` instead of  ``original.py``,
     but error messages will still reference ``original.py``.
 
+.. _enabling-incomplete-experimental-features:
+
+Experimental features
+*****************************************
+
+.. option:: --enable-incomplete-feature {PreciseTupleTypes, InlineTypedDict}
+
+    Some features may require several mypy releases to implement, for example
+    due to their complexity, potential for backwards incompatibility, or
+    ambiguous semantics that would benefit from feedback from the community.
+    You can enable such features for early preview using this flag. Note that
+    it is not guaranteed that all features will be ultimately enabled by
+    default. In *rare cases* we may decide to not go ahead with certain
+    features.
+
+    List of currently incomplete/experimental features:
+
+    * ``PreciseTupleTypes``: this feature will infer more precise tuple types in
+      various scenarios. Before variadic types were added to the Python type system
+      by :pep:`646`, it was impossible to express a type like "a tuple with
+      at least two integers". The best type available was ``tuple[int, ...]``.
+      Therefore, mypy applied very lenient checking for variable-length tuples.
+      Now this type can be expressed as ``tuple[int, int, *tuple[int, ...]]``.
+      For such more precise types (when explicitly *defined* by a user) mypy,
+      for example, warns about unsafe index access, and generally handles them
+      in a type-safe manner. However, to avoid problems in existing code, mypy
+      does not *infer* these precise types when it technically can. Here are
+      notable examples where ``PreciseTupleTypes`` infers more precise types:
+
+      .. code-block:: python
+
+         numbers: tuple[int, ...]
+
+         more_numbers = (1, *numbers, 1)
+         reveal_type(more_numbers)
+         # Without PreciseTupleTypes: tuple[int, ...]
+         # With PreciseTupleTypes: tuple[int, *tuple[int, ...], int]
+
+         other_numbers = (1, 1) + numbers
+         reveal_type(other_numbers)
+         # Without PreciseTupleTypes: tuple[int, ...]
+         # With PreciseTupleTypes: tuple[int, int, *tuple[int, ...]]
+
+         if len(numbers) > 2:
+             reveal_type(numbers)
+             # Without PreciseTupleTypes: tuple[int, ...]
+             # With PreciseTupleTypes: tuple[int, int, int, *tuple[int, ...]]
+         else:
+             reveal_type(numbers)
+             # Without PreciseTupleTypes: tuple[int, ...]
+             # With PreciseTupleTypes: tuple[()] | tuple[int] | tuple[int, int]
+
+    * ``InlineTypedDict``: this feature enables non-standard syntax for inline
+      :ref:`TypedDicts <typeddict>`, for example:
+
+      .. code-block:: python
+
+         def test_values() -> {"int": int, "str": str}:
+             return {"int": 42, "str": "test"}
+
+.. option:: --find-occurrences CLASS.MEMBER
+
+    This flag will make mypy print out all usages of a class member
+    based on static type information. This feature is experimental.
 
 Report generation
 *****************
@@ -1096,65 +1161,6 @@ format into the specified directory.
     ``mypy[reports]``.
 
 
-Enabling incomplete/experimental features
-*****************************************
-
-.. option:: --enable-incomplete-feature {PreciseTupleTypes, InlineTypedDict}
-
-    Some features may require several mypy releases to implement, for example
-    due to their complexity, potential for backwards incompatibility, or
-    ambiguous semantics that would benefit from feedback from the community.
-    You can enable such features for early preview using this flag. Note that
-    it is not guaranteed that all features will be ultimately enabled by
-    default. In *rare cases* we may decide to not go ahead with certain
-    features.
-
-List of currently incomplete/experimental features:
-
-* ``PreciseTupleTypes``: this feature will infer more precise tuple types in
-  various scenarios. Before variadic types were added to the Python type system
-  by :pep:`646`, it was impossible to express a type like "a tuple with
-  at least two integers". The best type available was ``tuple[int, ...]``.
-  Therefore, mypy applied very lenient checking for variable-length tuples.
-  Now this type can be expressed as ``tuple[int, int, *tuple[int, ...]]``.
-  For such more precise types (when explicitly *defined* by a user) mypy,
-  for example, warns about unsafe index access, and generally handles them
-  in a type-safe manner. However, to avoid problems in existing code, mypy
-  does not *infer* these precise types when it technically can. Here are
-  notable examples where ``PreciseTupleTypes`` infers more precise types:
-
-  .. code-block:: python
-
-     numbers: tuple[int, ...]
-
-     more_numbers = (1, *numbers, 1)
-     reveal_type(more_numbers)
-     # Without PreciseTupleTypes: tuple[int, ...]
-     # With PreciseTupleTypes: tuple[int, *tuple[int, ...], int]
-
-     other_numbers = (1, 1) + numbers
-     reveal_type(other_numbers)
-     # Without PreciseTupleTypes: tuple[int, ...]
-     # With PreciseTupleTypes: tuple[int, int, *tuple[int, ...]]
-
-     if len(numbers) > 2:
-         reveal_type(numbers)
-         # Without PreciseTupleTypes: tuple[int, ...]
-         # With PreciseTupleTypes: tuple[int, int, int, *tuple[int, ...]]
-     else:
-         reveal_type(numbers)
-         # Without PreciseTupleTypes: tuple[int, ...]
-         # With PreciseTupleTypes: tuple[()] | tuple[int] | tuple[int, int]
-
-* ``InlineTypedDict``: this feature enables non-standard syntax for inline
-  :ref:`TypedDicts <typeddict>`, for example:
-
-  .. code-block:: python
-
-     def test_values() -> {"int": int, "str": str}:
-         return {"int": 42, "str": "test"}
-
-
 Miscellaneous
 *************
 
@@ -1201,11 +1207,6 @@ Miscellaneous
     type checking results. This can make it easier to integrate mypy
     with continuous integration (CI) tools.
 
-.. option:: --find-occurrences CLASS.MEMBER
-
-    This flag will make mypy print out all usages of a class member
-    based on static type information. This feature is experimental.
-
 .. option:: --scripts-are-modules
 
     This flag will give command line arguments that appear to be