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

[Karsten Hilbert]

Am Sun, Oct 23, 2022 at 05:16:48PM -0400 schrieb Thomas Passin:

> >	def make_title_from_headline(self, p, h) -> str:
> >
> >	def plot(self, stackposition=MAIN, clearFirst=True) -> None:

> 1. Knowing the type of a parameter isn't all you usually want to know;

Sure, as I said:

> >and use RETURNS (or Returns:) only when what is returned
> >warrants further explanation (say, as to what is returned
> >when).

same for arguments, which *usually* warrant some further
explanation, except for rare cases such as

	def format_a_string(string2format:str=None) -> str:

where string2format just might not require further
explanation.

> 2. If the type information isn't in the docstring, it won't be reported by reporting
> tools that use the docstring.

While true such tools could be considered suboptimal (these
days, again as I said).

> Then there are all those cases where the signature hasn't been type-annotated

True but OPs question was *how* to document so there's no
perceived problem with having to document.

> 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.

+1

Karsten
--
GPG  40BE 5B0E C98E 1713 AFA6  5BC0 3BEA AC80 7D4F C89B