29

When I create a function with parameters, PyCharm offers me to create the docstring with :param param_name: field, which is pretty good. But I also need to add the :type param_name:.

So from that :

def foo(bar, xyz):
    return bar + xyz

With the generate docstring option i have that (even with Insert 'type' and 'rtype' to the documentation stub enable) :

def foo(bar, xyz):
    """
    :param bar:
    :param xyz:
    """
    return bar + xyz

And I would like that :

def foo(bar, xyz):
    """
    :param bar:
    :type bar:
    :param xyz:
    :type xyz:
    """
    return bar + xyz
nbro
  • 15,395
  • 32
  • 113
  • 196
FunkySayu
  • 7,641
  • 10
  • 38
  • 61

5 Answers5

16

Go to Settings > Editor > General > Smart Keys, then check the box that says Insert type placeholders in the documentation comment stub.

enter image description here

nbro
  • 15,395
  • 32
  • 113
  • 196
PinHao Bill Chen
  • 351
  • 2
  • 7
  • 6
    This setting is now in Editor->General->Smart Keys->Python. But I wonder if PyCHarm should automacitally get the `type` from my type annotation in the declaration of the method: `def check(self, key: str, not: str, id: str) -> str:` – bomben Jul 14 '21 at 07:11
15

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.

Note that the documentation has since been updated, the configuration guidance currently reads:

Enable documentation comments

  1. Open the Editor | General | Smart Keys page of PyCharm settings ⌃⌥S.

  2. In the Enter section, select or clear Insert documentation comment stub checkbox.

  3. Then, scroll to the Insert type placeholders in the documentation comment stub option and select or clear the checkbox as required. Refer to the option description for details.

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.

jonrsharpe
  • 115,751
  • 26
  • 228
  • 437
  • 1
    Doesn't work with me. I only have ":return: :rtype:" added (after a restart of pycharm also) – FunkySayu Jun 26 '15 at 09:45
  • @FunkySayu then please provide an example, or consider raising a bug report with the developers. – jonrsharpe Jun 26 '15 at 09:46
  • @FunkySayu it seems there is no one-step solution; I've updated the answer – jonrsharpe Jun 26 '15 at 11:58
  • erf... That was what i found too. Maybe i'll do a feature request for that. Thank you for your help anyway. – FunkySayu Jun 26 '15 at 12:30
  • 3
    I found something by chance : when you use Alt+Enter keys to generate the docstring, the solution doesn't work (the :type:, :return: :rtype: are not generated). BUT if you define your function and after you write """, the documentation is generated properly. Checkout if it works on your side, update your answer and I set it to solved. – FunkySayu Jun 29 '15 at 07:58
  • Hmmm it's not exact. It looks like it works some times and some other time not. Quite strange feature. – FunkySayu Jun 29 '15 at 10:14
  • Hmm, this almost works. My function is annotated, but the docstring does not report what is specified. Is this the expected behaviour? – Atcold Feb 14 '17 at 21:43
  • @Atcold could you expand on *"the docstring does not report what is specified"* - what is specified? What gets reported? – jonrsharpe Feb 14 '17 at 21:44
  • My function is `def fun(a: float) -> None: pass`. The auto-generated field `:type a:` is empty, while I expected `:type a: float`. Am I making sense at all? – Atcold Feb 14 '17 at 21:48
  • @Atcold yes, but I never said those stubs would be filled from annotations. If that's functionality you'd like, I suggest you raise it with JetBrains: https://youtrack.jetbrains.com/issues/PY – jonrsharpe Feb 14 '17 at 21:52
  • My bad. I was not questioning your answer. Just pointing out some expected behaviour. Thank you for the link. – Atcold Feb 14 '17 at 22:08
8

First, check if you have the restructuredText plugin enabled. To check, go to preferences - plugins - restructuredText (if not enabled check the box to enable it) Next, in the same preferences tab, navigate to Tools > Python Integrated Tools > Docstrings

Then:

  • Change the Docstring format: restructuredText (instead of Plain)
  • Check box "Analyze the python code in docstrings"
  • Check the box "Render external documentation for stdlib"

enter image description here Apply the changes and close.

Finally, to verify the changes, go to function block and add three quotes(single or double) and hit enter or space, you should see the docstring auto-generated.

dermen
  • 5,252
  • 4
  • 23
  • 34
Dry_accountant_09
  • 1,371
  • 16
  • 15
4

Just enable this checkbox:

Editor - General - Smart Keys - Insert type placeholders in the documentation comment stub.

Also remember to enable this item so that you can use the Alt+enter to auto insert documentation:

Editor - General - Smart Keys - Insert documentation comment stub

jonrsharpe
  • 115,751
  • 26
  • 228
  • 437
Woogux Wu
  • 145
  • 1
  • 9
2

What you asked already has been replied but I find relevant to point that you can use 

def foo(bar, xyz):
    """


    :param bar_type bar:
    :param xyz_type xyz:
    """
    return bar + xyz

Use indicate bar_type and xyz_type the types of the variables. A good tip is that you can use | to set more than one possible type. Example:

def foo(bar, xyz):
    """


    :param float|int bar:
    :param numpy.array xyz:
    """
    return bar + xyz
Marco Aguiar
  • 59
  • 5