PyCharm on OSX: Missing "Insert Documentation Comment Stub"


I've been working in PyCharm on and off for about a year and recently started hammering away at a project that has grown to about 1500 lines.  I'd just been manually commenting with #'s like I used to do with C++ 15 years ago.  A coworker told me I was a big dummy because I could automagically comment with """+Enter.  What?  Awesome!  

But then I go into the editor Smart Keys and the option to enable the feature doesn't even exist.  I've also attempted to use Ctrl+Shift+A to "Fix" the comments but nothing happens.  I compared my install to his and we found no missing packages.  I've gone back to older versions and nothing (didn't kill my settings, though).

Has anyone else experienced this?  I wanted to break out all my classes into different documents but I'm not going to manually redocument 15 classes if I don't have to.

Comment actions Permalink

Hi Stephen. Sorry for the late reply.

UPD: I didn't read the title carefully. Please don't mind the following two paragraphs :)

Could you please clarify a bit what exactly you need -- comment something out with triple quotes instead of "#" or insert docstrings? Meanwhile, these are my thoughts.

Strictly speaking, triple quoted string literals weren't meant to be used as block comments. At least, we stick to this point of view, though, well, GvR suggests the opposite. It's somewhat fragile technique because you may have other triple quoted strings inside the commented fragment and it will inevitably break the program structure. Additionally, such triple quoted part of a program might accidentally get recognized as the docstring. Why do you need this "trick", after all, if you can simply select the necessary lines in the editor and hit "Ctrl+/" to comment them with "#"?

What your coworker is referring to seems to be the feature that allows to generate docstring skeletons for function definitions. It works as follows:

You write triple quotes right after the function header and then hit Enter:

def make_sandwich(spam,eggs,bacon,ham=None,**other):

You will get a docstring pre-populated with appropriate "magic" tags and sections according to the docstring format you picked in Settings | Tools | Python Integrated Tools | Docstring format.

def make_sandwich(spam,eggs,bacon,ham=None,**other):

:param spam:
:param eggs:
:param bacon:
:param ham:
:param other:

Whether this feature is enabled is controlled by the option Settings | Editor | General | Smart Keys | Insert documentation comment stub. Also you can insert additional tags and sections for type annotations using Settings | Editor | General | Smart Keys | Insert type placeholders in the documentation comment stub.

Comment actions Permalink

I was really absent minded. Could you please attach a screenshot of the "Smart Keys" settings page? I'm wondering for what reason this option might be missing in the distribution. Is it still relevant in the recent updates of PyCharm, e.g. 2016.2.2?


Please sign in to leave a comment.