Việc sử dụng mẫu docstring của PyCharm là gì? Làm thế nào để sử dụng nó một cách hiệu quả?

Question

PyCharm, Python IDE tạo mẫu cho docstring khi tôi bắt đầu nhập vào chuỗi tài liệu. Đây là mẫu được tạo cho một hàm đơn giản.

def add_them(x, y): 
    """ 

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

Tôi không tìm thấy bất kỳ điều gì tương tự với mã vạch chính thức của Python conventions.

Mẫu này có sử dụng bất kỳ trình tạo tài liệu nào như readthedocs không?

Làm cách nào để người nào đó sử dụng hiệu quả?

Cách thích hợp để điền mẫu là gì?

cảm ơn.

Answer 1

Chúng tôi sử dụng nó với sphinx-apidoc để tạo tài liệu HTML và PDF của chúng tôi.

Dưới đây là một ví dụ làm thế nào tôi sử dụng 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 

    """