Parameter documentation
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* *"""*
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:
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:
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:
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:
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:
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:
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:
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:
participants (2)
-
abed...＠gmail.com -
Paul Bryan