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
> <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/4YJIVCZ5OIACU74UGZJECRMLTZWVDMOZ/
Code of Conduct: http://python.org/psf/codeofconduct/
