Perhaps this would be a good opportunity to start looking at typing.Annotated[...] as a mechanism for parameter documentation? Something like:
def request(
method: Annotated[str, Doc("The method to perform")], url: Annotated[str, Doc("The URL to submit request to")], ...
) -> Response:
"""Constructs and sends a request."""
...
Sorry, I accidentally hit "post message" too soon. The idea is that python would somehow construct a more complete doc-string from the function doc-string and it's signature/parameter doc-strings.
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"""
_______________________________________________
_______________________________________________