CODEWITHSUNDEEP
pycharm
gnychis
gnychis

Reputation: 7555

Documenting Python parameters in docstring using PyCharm

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:

enter image description here

(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:

enter image description here

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

enter image description here

(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):

enter image description here

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

enter image description here

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).

Upvotes: 15

Views: 28004

Answers (3)

WesternGun
WesternGun

Reputation: 12728

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

Upvotes: 12

Roman
Roman

Reputation: 9441

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:

...

  1. 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: 
    """

Upvotes: 4

Nikolay Prokopyev
Nikolay Prokopyev

Reputation: 1312

It works on the latest version of PyCharm (2016.2 CE) and even in some previous patched versions.

it works! (Screenshot)

I asked similar question and got an answer!

PyCharm and reStructuredText (Sphinx) documentation popups

Upvotes: 0

Related Questions