Documenting Python parameters in docstring using PyCharm

Question

I'm having some trouble figuring out the proper way to document a method in Pycharm to achieve type hints AND parameter description.

In Pycharm's documentation it suggests:

:param "type_name" "param_name": "param_description"

(1) However, when I try to use that, the function definition does not properly show the parameter description:

(2) If I switch to leading with the @ sign I get a list of parameters and their types, but I do not get the parameter description:

(3) If I stick with the @ sign and drop the types, I get the parameter descriptions:

(4) If I explicitly add @type for each @param (which completely blows up the size of the comment block), everything works properly (but I hate the size of the comment):

(5) Finally, for sake of completeness, using : instead of @ causes everything to fail to populate:

Note that I have tried changing the documentation system within Pycharm, but it doesn't affect how it renders the documentation -- it only seems to affect how it autopopulates a comment block for you.

How can I achieve documentation as close to example (1) which is compact, but actually have it populate the function definition properly? I'd hate to be stuck with style (4).

Solution 1

Have you checked Settings... - Tools - Python integrated tools - Docstring format? You can choose the parsing style.

You can choose from:

• Plain
• Epytext
• reStructuredText
• Numpy
• Google

Solution 2

Copied straight from Pycharm: Auto generate `:type param:` field in docstring:

---

Per the documentation:

If configured, the documentation comment stubs can be generated with type and rtype tags.

Following the link:

...

3. In the Smart Keys page, select the check box Insert 'type' and 'rtype' to the documentation comment stub.

Once you have done this, put the cursor in a parameter name in the definition, activate the Smart Keys feature (Alt+Enter, by default) and select Specify type for reference in docstring. This will insert the appropriate comment line . Similarly you can put the cursor in the function/method name and select Specify return type in docstring.

---

So now if you type """ after a function declaration it creates them automatically for you:

def funct(a, b, c):
    """
    :param a: 
    :type a: 
    :param b: 
    :type b: 
    :param c: 
    :type c: 
    :return: 
    :rtype: 
    """

Comments

[Dev Sareno]

Select reStructuredText for :param format. Works for me 👍