What is the use of the PyCharm docstring pattern? How can I use it effectively?

Question

PyCharm, the Python IDE generates a template for docstring when I start typing in docstring. This is a template generated for a simple function.

def add_them(x, y): """ :param x: :param y: :return: """ z = x + y return z 

I do not find it similar to the official docstring Python convention .

Is this template used for any documentation generators like readthedocs?

How to use someone effectively?

What is the correct way to populate a template?

thanks.

Answer 1

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

Here is an example of how I use 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 """