A trivial question that I don't know - document a function/method
Dan Stromberg
drsalists at gmail.com
Sat Oct 22 19:09:11 EDT 2022
I don't think there is a "correct" way. It depends somewhat on what tools
you're using. I like pydocstyle, which I have hung off of vim with
syntastic. pydocstyle checks for https://peps.python.org/pep-0257/
conformance.
Also, rather than describe the types of formal parameters to functions in a
docstring, I like to use mypy for https://peps.python.org/pep-0484/ with
its --disallow-untyped-calls and --ignore-missing-imports options, which I
hang off of a Makefile, called by a vim macro.
On Sat, Oct 22, 2022 at 3:39 PM Paulo da Silva <
p_d_a_s_i_l_v_a_ns at nonetnoaddress.pt> wrote:
> 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
>
More information about the Python-list
mailing list