DOC: Add correctness vs strictness consideration for np.dtype (#16917)

* DOC: Add correctness vs strictness consideration for np.dtype

* MAINT: Update numpy/typing/__init__.py

Co-authored-by: Ross Barnowski <rossbar@berkeley.edu>

* MAINT: Update numpy/typing/__init__.py

Co-authored-by: Bas van Beek <43369155+BvB93@users.noreply.github.com>

* MAINT: Change type to static type to differentiate from type objects

* MAINT: Revert static type change

Co-authored-by: Ross Barnowski <rossbar@berkeley.edu>
Co-authored-by: Bas van Beek <43369155+BvB93@users.noreply.github.com>

1 files changed, 16 insertions, 2 deletions

diff --git a/numpy/typing/__init__.py b/numpy/typing/__init__.py
index f2000823f..3a00162cb 100644
--- a/numpy/typing/__init__.py
+++ b/numpy/typing/__init__.py
@@ -68,13 +68,27 @@ the following code is valid:
 
 .. code-block:: python
 
-    x = np.array([1, 2])
-    x.dtype = np.bool_
+    >>> x = np.array([1, 2])
+    >>> x.dtype = np.bool_
 
 This sort of mutation is not allowed by the types. Users who want to
 write statically typed code should insted use the `numpy.ndarray.view`
 method to create a view of the array with a different dtype.
 
+dtype
+~~~~~
+
+The ``DTypeLike`` type tries to avoid creation of dtype objects using
+dictionary of fields like below:
+
+.. code-block:: python
+
+    >>> x = np.dtype({"field1": (float, 1), "field2": (int, 3)})
+
+Although this is valid Numpy code, the type checker will complain about it,
+since its usage is discouraged.
+Please see : https://numpy.org/devdocs/reference/arrays.dtypes.html
+
 """
 from ._array_like import _SupportsArray, ArrayLike
 from ._shape import _Shape, _ShapeLike