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*
*"""*