PyCharm function documentation style and preview

Answered

Hello,

currently PyCharm offers generating docstring for a function in the style:

"""
Function's description
:param param_no_1: parameter #1 description
:param param_no_2: parameter #2 descrption
:return: returning variable description
"""

Where can I see the generated documentation for these docstrings?

Quick-doc (ctrl+q), as far as I have seen, mashes everything into one paragraph

4 comments
Comment actions Permalink

Hi Paulius,

 

We use docutils to extract information about the parameters and the return value of a function. It seems that you need to put a blank line after "Function's description" so that the corresponding tags would be parsed out properly. After that the docstring for this example would be displayed like the following:

 



1
Comment actions Permalink

Thank you, this resolves the problem!

0
Comment actions Permalink

> It seems that you need to put a blank line after "Function's description"

 

This is kinda an annoying requirement. Some will argue it looks better with a blank line, but I think:

1. it wastes unnecessary vertical space

2. it's very easy to forget and its something typically noticed a long time after. Maybe in a completely unrelated branch. Fixing it on-demand might cause unnecessary merge conflicts or force the person noticing it to swithc branches.

 

0
Comment actions Permalink

Hello, 

 

please vote for the usability problem reported https://youtrack.jetbrains.com/issue/PY-26281 in order to increase its priority. 

0

Please sign in to leave a comment.