Currently, python allows variable documentation via PEP 526
<https://www.python.org/dev/peps/pep-0526/>. For most functions with short
parameter lists that can fit in a reasonable column limit, I prefer the
traditional declaration style with Google-style doc strings:
*def connect_to_next_port(self, minimum: int) => int: *
"""Connects to the next available port.
Args:
minimum: A port value greater or equal to 1024.
Returns:
The new minimum port.
Raises:
ConnectionError: If no available port is found.
"""
...code...
However, when a signature gets too long, I prefer to list the parameters
vertically:
*def request(*
* method: Method, url: Str,*
* params: Dict = None, data: Dict = None, json: Str =
None, headers: Dict = None, cookies: Dict = None,
files: Dict = None, ...) => Response: """*
*Constructs and sends a Request*
* Args: ... """ *
In which case, it would be nice to in-line some documentation instead of
repeating the whole parameter list in the doc string. Something like:
*def request(*
* method: Method*
* #method for the new Request: ``GET``,``POST``, etc.*
* , url: Str*
* #URL for the request ,*
* params: Dict = None*
* ...**) => Response:*
* """**Constructs and sends a Request*
*"""*
_______________________________________________
Python-ideas mailing list -- python-ideas@python.org
To unsubscribe send an email to python-ideas-le...@python.org
https://mail.python.org/mailman3/lists/python-ideas.python.org/
Message archived at
https://mail.python.org/archives/list/python-ideas@python.org/message/JJZA6AHKQCTB47GX5RWHATZ447AUADQ4/
Code of Conduct: http://python.org/psf/codeofconduct/
