Add a few docstring improvements and fixes

changelog.d/859.change.rst

@@ -1,4 +1,4 @@
 Added new context manager ``attr.validators.disabled()`` and functions ``attr.validators.(set|get)_disabled()``.
 They deprecate ``attr.(set|get)_run_validators()``.
 All functions are interoperable and modify the same internal state.
-They are not thread-safe, though.
+They are not – and never where – thread-safe, though.

docs/api.rst

@@ -590,7 +590,7 @@ Validators
             ...
         TypeError: ("'x' must be <class 'str'> (got 7 that is a <class 'int'>).", Attribute(name='x', default=NOTHING, validator=<deep_mapping validator for objects mapping <instance_of validator for type <class 'str'>> to <instance_of validator for type <class 'int'>>>, repr=True, cmp=True, hash=None, init=True, metadata=mappingproxy({}), type=None, converter=None, kw_only=False), <class 'str'>, 7)
 
-Validators can be globally disabled if you want to run them only in development and tests but not in production because you fear their performance impact:
+Validators can be both globally and locally disabled:
 
 .. autofunction:: attr.validators.set_disabled
 

src/attr/__init__.pyi

@@ -474,7 +474,6 @@ def evolve(inst: _T, **changes: Any) -> _T: ...
 
 def set_run_validators(run: bool) -> None: ...
 def get_run_validators() -> bool: ...
-def no_run_validators() -> ContextManager[None]: ...
 
 # aliases --
 

src/attr/_config.py

@@ -10,8 +10,9 @@ def set_run_validators(run):
     """
     Set whether or not validators are run.  By default, they are run.
 
-    .. deprecated:: 21.3.0 will not be moved to new ``attrs`` namespace.
-        Use :func:`attr.validators.set_disabled()` instead.
+    .. deprecated:: 21.3.0 It will not be removed, but it also will not be
+        moved to new ``attrs`` namespace.  Use `attr.validators.set_disabled()`
+        instead.
     """
     if not isinstance(run, bool):
         raise TypeError("'run' must be bool.")
@@ -23,7 +24,8 @@ def get_run_validators():
     """
     Return whether or not validators are run.
 
-    .. deprecated:: 21.3.0 will not be moved to new ``attrs`` namespace.
-        Use :func:`attr.validators.get_disabled()` instead.
+    .. deprecated:: 21.3.0 It will not be removed, but it also will not be
+        moved to new ``attrs`` namespace.  Use `attr.validators.get_disabled()`
+        instead.
     """
     return _run_validators

src/attr/validators.pyi

@@ -26,6 +26,10 @@ _K = TypeVar("_K")
 _V = TypeVar("_V")
 _M = TypeVar("_M", bound=Mapping)
 
+def set_disabled(run: bool) -> None: ...
+def get_disabled() -> bool: ...
+def disabled() -> ContextManager[None]: ...
+
 # To be more precise on instance_of use some overloads.
 # If there are more than 3 items in the tuple then we fall back to Any
 @overload