From 8ded1f06ba5f4ad16bfc98e5f17c8f21b931dc2a Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Mon, 2 Jun 2025 23:46:05 +0200
Subject: [PATCH] DOC: Clarify that types in docstrings do not use formal type
 annotation syntax

---
 doc/devel/document.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/doc/devel/document.rst b/doc/devel/document.rst
index 20c30acf66aa..1119a265a80d 100644
--- a/doc/devel/document.rst
+++ b/doc/devel/document.rst
@@ -537,6 +537,10 @@ understandable by humans. If the possible types are too complex use a
 simplification for the type description and explain the type more
 precisely in the text.
 
+We do not use formal type annotation syntax for type descriptions in
+docstrings; e.g. we use ``list of str`` rather than  ``list[str]``; we
+use ``int or str`` rather than ``int | str`` or ``Union[int, str]``.
+
 Generally, the `numpydoc docstring guide`_ conventions apply. The following
 rules expand on them where the numpydoc conventions are not specific.