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

[Schachner, Joseph (US)]

I head a small software team much of whose output is Python.   I would gratefully accept any of the formats you show below.  My preference is #1.

--- Joseph S.


Teledyne Confidential; Commercially Sensitive Business Data

-----Original Message-----
From: Paulo da Silva <p_d_a_s_i_l_v_a_ns at nonetnoaddress.pt> 
Sent: Saturday, October 22, 2022 4:58 PM
To: python-list at python.org
Subject: A trivial question that I don't know - document a function/method

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