A trivial question that I don't know - document a function/method
Karsten Hilbert
Karsten.Hilbert at gmx.net
Sun Oct 23 17:49:22 EDT 2022
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
More information about the Python-list
mailing list