12

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

Mikko Ohtamaa
  • 82,057
  • 50
  • 264
  • 435
gnychis
  • 7,289
  • 18
  • 75
  • 113
  • 1
    Please note that for Python 3 you can use native Python annotation: https://www.python.org/dev/peps/pep-0484/ - a feature which will receive update in Python 3.5 – Mikko Ohtamaa Aug 03 '15 at 22:17
  • Didn't know that it worked with @ – Hydren Nov 17 '15 at 14:18
  • Oddly enough, I found out that when the documentation is generated by typing """ then toggling auto-complete, PyCharm seems to recognize example 5. – Hydren Nov 17 '15 at 17:45

3 Answers3

11

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
WesternGun
  • 11,303
  • 6
  • 88
  • 157
4

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: 
    """
Community
  • 1
  • 1
Roman
  • 8,826
  • 10
  • 63
  • 103
0

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

Community
  • 1
  • 1
Nikolay Prokopyev
  • 1,260
  • 12
  • 22