A trivial question that I don't know - document a function/method

[Thomas Passin]

On 10/23/2022 2:37 PM, Karsten Hilbert wrote:
> Am Sat, Oct 22, 2022 at 09:49:55PM -0400 schrieb Thomas Passin:
> 
>> def make_title_from_headline(self, p, h):
>>      """From node title, return title with over- and underline- strings.
> ...
>>         RETURNS
>>         a string
>>      """
> ....
>> def plot(self, stackposition=MAIN, clearFirst=True):
>>      """Plot a 2-D graph.
> ...
>>      RETURNS
>>      nothing
>>      """
> 
> Would it not, these days, be clearer to
> 
> 	def make_title_from_headline(self, p, h) -> str:
> 
> 	def plot(self, stackposition=MAIN, clearFirst=True) -> None:
> 
> and use RETURNS (or Returns:) only when what is returned
> warrants further explanation (say, as to what is returned
> when).

It might, but remember:

1. Knowing the type of a parameter isn't all you usually want to know;
2. If the type information isn't in the docstring, it won't be reported 
by reporting tools that use the docstring.

Then there are all those cases where the signature hasn't been 
type-annotated, either because adding them to existing code would be a 
big burden, or because the developer feels it's too much trouble, all 
things considered.

I would say that if the types are annotated, the method is simple 
enough, and the names are clear enough, sure, go ahead and rely on the 
type annotations.  The most important thing is that readers can 
understand what the arguments and returns are intended to be, so some 
flexibility makes sense.