CODEWITHSUNDEEP
pythoncoding-styledocumentationpycharmdocstring
user3348051
user3348051

Reputation:

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

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.

Upvotes: 7

Views: 3855

Answers (1)

stevieb
stevieb

Reputation: 9296

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

    """

Upvotes: 13

Related Questions