diff --git a/doc/source/AUTHORS b/doc/source/AUTHORS index 09733889..1ef3eab7 100644 --- a/doc/source/AUTHORS +++ b/doc/source/AUTHORS @@ -34,6 +34,7 @@ Chronological list of authors - Cédric Bouysset 2022 - Florent Langenfeld + - Kavya Bisht - Bjarne Feddersen - Mark Verma - Patricio Barletta diff --git a/doc/source/contributing_code.rst b/doc/source/contributing_code.rst index 65bc8c98..447ac93c 100644 --- a/doc/source/contributing_code.rst +++ b/doc/source/contributing_code.rst @@ -740,7 +740,7 @@ A typical function docstring looks like the following: :: - def func(arg1, arg2): + def func(arg1, arg2, arg3): """Summary line. Extended description of function. @@ -751,6 +751,8 @@ A typical function docstring looks like the following: Description of `arg1` arg2 : str Description of `arg2` + arg3 : list[int] + Description of `arg3` Returns @@ -761,6 +763,18 @@ A typical function docstring looks like the following: """ return True +.. note:: + + While MDAnalysis continues to support Python versions under 3.9, + type hinting should follow the syntax first laid out in + `PEP 484 – Type Hints `_. + However, as shown in the example above, function **documentation** + should follow the type hinting recommendations laid out in + `PEP 585 – Type Hinting Generics In Standard Collections `_. + That means that for now, type hinting should still import from ``typing`` + and a dictionary would still be hinted as ``Dict[Tuple[str, str], int]``. + However, the corresponding docstring would describe the argument as ``dict[tuple[str, str], int]``. + .. seealso:: The `napoleon documentation `_ has further breakdowns of docstrings at the module, function, class, method, variable, and other levels.