Hi all!
What is the correct way, if any, of documenting a function/method?
1.
def foo(a,b):
""" A description.
a: Whatever 1
b: Whatever 2
"""
...
2.
def foo(a,b):
""" A description.
a -- Whatever 1
b -- Whatever 2
"""
...
3.
def foo(a,b):
""" A description.
@param a: Whatever 1
@param b: Whatever 2
"""
...
4.
def foo(a,b):
""" A description.
:param a: Whatever 1
:param b: Whatever 2
"""
...
5.
Any other ...
Any comments/suggestions are welcome.
Thanks.
Paulo
--
https://mail.python.org/mailman/listinfo/python-list
Hi all![snip]
What is the correct way, if any, of documenting a function/method?
1.
def foo(a,b):
""" A description.
a: Whatever 1
b: Whatever 2
"""
5.
Any other ...
Any comments/suggestions are welcome.
Thanks.
Paulo
What is the correct way, if any, of documenting a function/method?
5.
Any other ...
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
"""
Hi all!
What is the correct way, if any, of documenting a function/method?
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;
and use RETURNS (or Returns:) only when what is returned
warrants further explanation (say, as to what is returned
when).
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
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.
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).
Às 21:58 de 22/10/22, Paulo da Silva escreveu:
Hi all!
What is the correct way, if any, of documenting a function/method?
Thank you all for the, valuable as usual, suggestions.
I am now able to make my choices.
Paulo
Sysop: | Keyop |
---|---|
Location: | Huddersfield, West Yorkshire, UK |
Users: | 300 |
Nodes: | 16 (2 / 14) |
Uptime: | 61:01:06 |
Calls: | 6,712 |
Files: | 12,244 |
Messages: | 5,355,765 |