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

[Dan Stromberg]

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
>