Qual è l'uso del modello docstring di PyCharm? Come lo uso in modo efficace?

Question

PyCharm, l'IDE Python genera un modello per docstring mentre inizio a digitare la docstring. Questo è il modello generato per una semplice funzione.

def add_them(x, y): 
    """ 

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

I dont trovare qualcosa di simile a docstring ufficiale di Python conventions.

Questo modello è utile con qualsiasi generatore di documentazione come readthedoc?

Come qualcuno usa in modo efficace?

Qual è il modo corretto di riempire il modello?

grazie.

Answer 1

Lo usiamo con sphinx-apidoc per generare la nostra documentazione HTML e PDF.

Ecco un esempio di come io uso le 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 

    """