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, 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 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.

        minimum: A port value greater or equal to 1024.

        The new minimum port.

        ConnectionError: If no available port is found.

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 --
To unsubscribe send an email to
Message archived at
Code of Conduct: