@maurycy noticed in #137949 that the csv.register_dialect() docstring creates an incorrect impression that the function returns the registered dialect, while it always returns None.
Removing assignment in the docstring would fix this error, but the docstring will still not be in the best shape. It is not common to add a signature at the end of the docstring. It is usually added at the beginning of docstring, and if possible, written if form recognized as text signature.
The same is true for othe functions in the csv module which contain a hybrid of signature and trivial usage example. For functions that were converted to Argument Clinic, the signature is repeated twice.
So, I think to use opportunity to fix an error in the csv.register_dialect() docstring and improve all other docstrings. We usually do not backport docstring improvement changes, but in this case they are too bad (and conversion to Argument Clinic made the help output worse).
Linked PRs
@maurycy noticed in #137949 that the
csv.register_dialect()docstring creates an incorrect impression that the function returns the registered dialect, while it always returns None.Removing assignment in the docstring would fix this error, but the docstring will still not be in the best shape. It is not common to add a signature at the end of the docstring. It is usually added at the beginning of docstring, and if possible, written if form recognized as text signature.
The same is true for othe functions in the csv module which contain a hybrid of signature and trivial usage example. For functions that were converted to Argument Clinic, the signature is repeated twice.
So, I think to use opportunity to fix an error in the
csv.register_dialect()docstring and improve all other docstrings. We usually do not backport docstring improvement changes, but in this case they are too bad (and conversion to Argument Clinic made the help output worse).Linked PRs
csv.register_dialectdocstring #137949 (superseded by gh-137986: Fix and improve the csv functions docstrings #137987)