PyCharm 3.4.0 Web Help

In this section:

Please note the following:

  • PyCharm checks syntax in the documentation comments and treats it according to the Error settings.
  • If the entered text contains HTML tags, the closing tag will be automatically added after typing >, provided that this behavior is enabled in the editor settings.
  • When typing in a documentation comment, the caret automatically moves to an expected position. For example:

    javadoc_smart_enter

To create documentation comment for a Python function
  1. Place the caret after the declaration of a function you want to document.
  2. Type opening triple quotes, and press EnterEnterEnterEnterEnterEnterEnterEnterEnterEnterEnter, or Space.
  3. Add meaningful description of parameters and return values.

Tip

If you rename a parameter of a function, PyCharm will correspondingly update the tag in documentation comment.

To create documentation comment for a Python function using intention action
  1. Place the caret somewhere within the function you want to document.
  2. Press Alt+EnterAlt+EnterAlt+EnterAlt+EnterAlt+EnterAlt+EnterAlt+EnterAlt+Enter, Shift+Alt+J or Ctrl+Shift+MAlt EnterAlt EnterCommand 1 to show the available intention actions.
  3. Choose Insert documentation string stub:

    py_doc_comment_qf

    PyCharm generates documentation comment stub according to docstring format, selected in the Python Integrated Tools page.

To create tags in a documentation comment block
  1. In a comment block, select the desired empty line and type @ or : character.
  2. Press Ctrl+SpaceCtrl+SpaceCtrl+SpaceCtrl+SpaceAlt+SlashCtrl+SpaceCtrl+Space or Ctrl+Back SlashCtrl+SpaceControl SpaceControl SpaceControl Space, or just wait for Code Completion to display the suggestion list:

    py_doc_comment_tags

  3. Select a tag from the suggestion list. For example, you can specify the parameters type, or return type.
  4. If a certain tag has several values, press Ctrl+SpaceCtrl+SpaceCtrl+SpaceCtrl+SpaceAlt+SlashCtrl+SpaceCtrl+Space or Ctrl+Back SlashCtrl+SpaceControl SpaceControl SpaceControl Space after the tag, and select the desired value from the suggestion list. For example, PyCharm suggests to select the desired parameter name.

    py_param_completion

Example of Python comment

Consider the following function:

      def handle(self, myParam1, myParam2):
        

In the Python Integrated Tools page, select Epytext. Then type the opening triple quotes and press EnterEnterEnterEnterEnterEnterEnterEnterEnterEnterEnter or Space. PyCharm generates documentation comment stub:

       ''' 
       @param self: 
       @param myParam1: 
       @param myParam2: 
       @return: 
       ''' 
    

Then select reStructuredText, type the opening triple quotes and press EnterEnterEnterEnterEnterEnterEnterEnterEnterEnterEnter or Space. PyCharm generates documentation comment stub:

       ''' 
       :param self: 
       :param myParam1: 
       :param myParam2: 
       :return: 
       ''' 
    
2.7+

Documentation comment can be created with the dedicated action Fix Doc Comment. It can be invoked by means of Find Action command.

Press Ctrl+Shift+ACtrl+Shift+ACtrl+Shift+ACtrl+Shift+ACtrl+Shift+ACtrl+Shift+ACtrl+ICtrl+Shift+AShift Command AShift Command ACommand 3, with the caret somewhere within a class, method, function, or field, which should be documented, and enter the action name Fix Doc String. The missing documentation stub with the corresponding tags is added. For example:

         function loadDocs(myParam1, myParam2){}

Type the opening documentation comment and press EnterEnterEnterEnterEnterEnterEnterEnterEnterEnterEnter to generate the documentation comment stub:

/**
* @param myParam1
* @param myParam2
*/

The next case lays with fixing problems in the existing documentation comments.

For example, if a method signature has been changed, PyCharm highlights a tag that doesn't match the method signature, and suggests an intention action UpdateJSDoc comment. You can also press Ctrl+Shift+ACtrl+Shift+ACtrl+Shift+ACtrl+Shift+ACtrl+Shift+ACtrl+Shift+ACtrl+ICtrl+Shift+AShift Command AShift Command ACommand 3, and type the action name:

fix_doc_comment_js

Note that the action has no keyboard shortcut bound with it. You can do it as described in the section Configuring Keyboard Shortcuts.

See Also

Procedures:

Reference:

External Links:

Web Resources: