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.""" ...
On Fri, 2021-01-29 at 12:33 -0800, abed...@gmail.com wrote:
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.
On Friday, January 29, 2021 at 2:29:51 PM UTC-6 abed...@gmail.com wrote:
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"""
Python-ideas mailing list -- python-ideas@python.org To unsubscribe send an email to python-ideas-leave@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/4YJIVC... Code of Conduct: http://python.org/psf/codeofconduct/