What is the use of PyCharm's docstring template? How do I use it effectively?

Question

PyCharm, the Python IDE generate a template for docstring as I start to type in the docstring. This is the template generated for a simple function.

def add_them(x, y):
    """

    :param x: 
    :param y: 
    :return:
    """
    z = x + y
    return z

I dont find it anything similar to the Python's official docstring conventions.

Does this template has any use with any documentation generators like readthedocs?

How do someone use effectively?

What is the proper way to fill the template?

thanks.

stevieb · Accepted Answer · 2015-06-01T15:18:22.970

13

We use it with sphinx-apidoc to generate our HTML and PDF documentation.

Here's an example how I use the docstrings:

def add_pdr(process, userid, log):
    """ Create and perform the target account operation PDR

    If the function/method is complex, I'd put a short one-line
    summary in the first line above, and a more detailed explanation
    here.

    :param dict process: dict of process details
    :param str userid: userid to perform actions on
    :param obj log: log object to perform logging to

    :raises KeyError: if the userid doesn't exist
    :raises APIError: if process dict is invalid

    :return: True on success, False upon failure

    """

edited Jun 01 '15 at 15:18

answered Jun 01 '15 at 14:54

stevieb

9,065
3
26
36

2

would you update the answer with example for `exception` too? – Jun 01 '15 at 15:10
2

Added exception/raises example – stevieb Jun 01 '15 at 15:22
1

is the parameter type entered by the user or auto generated? – Jun 01 '15 at 16:35
Sorry for this bump, but I liked this "template" very much. However, would you recommend using `:rtype` aswell to specify the type of the returned variable? – Ray Jun 27 '17 at 22:41
1

@RayKoopa Yes. We use `:rtype` as well, quite often. – stevieb Sep 11 '18 at 20:29

What is the use of PyCharm's docstring template? How do I use it effectively?

1 Answers1