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...@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 > -- https://mail.python.org/mailman/listinfo/python-list
