That could work. I'm not super familiar with typing.Annotated. I was hoping 
for something a little less though my example doesn't really show that with 
the way used commas.
Thinking about it more, it should be possible for the parser to recognize a 
comma followed by a comment within a function signature, so something like 
the following should be possible:

def request(
    method: str, # the method to perform
    url: str, # the URL to submit request for
    ...
) -> Response: # the response to the request
    """Constructs and sends a request."""
    ...

Though it's a bit of a special case because you can't remove the 
white-space and get the same result:

def request(method: str, # The method to perform url: str, # this doesn't 
work ...
) -> Response:
    # This also is a bit weird
    """Constructs and sends a request"""

so maybe it's better to mandate that the doc be a string literal:

def request(
    method: str, "the method to perform"
    url: str, "the URL to submit request for"
    ...
) -> Response: "the response to the request"
    """Constructs and sends a request."""
    ...

Which would look weird with different white-space, but be equivalent:

def request(method: str, "The method to perform" url: str, "this doesn't 
work" ...
) -> Response:
    """This also is a bit weird"""
    """Constructs and sends a request"""

The weirdest part about that is the doc string for "method" is after the 
comma and precedes "url".

Anyway, this was a half-baked thought for reducing some minor repetition 
and putting documentation closer to where it's relevant. If it comes at the 
expense of a lot of noise (Annotated[] everywhere) or a confusing syntax 
hack (like above), it's probably not worth it.
On Friday, January 29, 2021 at 2:46:55 PM UTC-6 Paul Bryan wrote:

> Or now, thinking more about it, why not simplify it by having a string 
> literal in Annotated just represent its docstring? 
>
> def request(
>
>     method: Annotated[str, "The method to perform"],
>
>     url: Annotated[str, "The URL to submit request to"],
>
>     ...
>
> ) -> Response:
>
>     """Constructs and sends a request."""
>
>     ...
>
>
>
> On Fri, 2021-01-29 at 20:40 +0000, Paul Bryan wrote:
>
> 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 
> <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...@python.org
> To unsubscribe send an email to python-id...@python.org
> https://mail.python.org/mailman3/lists/python-ideas.python.org/
> Message archived at 
> https://mail.python.org/archives/list/python...@python.org/message/4YJIVCZ5OIACU74UGZJECRMLTZWVDMOZ/
>  
> <https://mail.python.org/archives/list/python-ideas@python.org/message/4YJIVCZ5OIACU74UGZJECRMLTZWVDMOZ/>
> Code of Conduct: http://python.org/psf/codeofconduct/
> _______________________________________________
> Python-ideas mailing list -- python...@python.org
> To unsubscribe send an email to python-id...@python.org
> https://mail.python.org/mailman3/lists/python-ideas.python.org/
>
> Message archived at 
> https://mail.python.org/archives/list/python...@python.org/message/5LUVCKIFIFV7FI6HT55L2PNCDE355LXC/
>  
> <https://mail.python.org/archives/list/python-ideas@python.org/message/5LUVCKIFIFV7FI6HT55L2PNCDE355LXC/>
>
> Code of Conduct: http://python.org/psf/codeofconduct/
>
>
_______________________________________________
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/5VYNV7ZYDWTI3D3MWF4PH7YBDUPHERDW/
Code of Conduct: http://python.org/psf/codeofconduct/

Reply via email to