Currently, python allows variable documentation via PEP 526. 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"""