Le linee guida generali che stai cercando sono a destra in PEP257 in quello che hai citato, forse hai solo bisogno di vederlo in azione.
vostra funzione è un buon candidato per una sola linea di docstring ("casi davvero evidente"):
def script_running(self, script):
"""Check if the script is running."""
Di solito se si dice che una funzione sta controllando qualcosa vuol dire che sta andando a tornare True o False, ma se vi piace si può essere più precisi:
def script_running(self, script):
"""Return True if the script is running, False otherwise."""
ancora una volta tutto in una sola riga.
Probabilmente cambierei anche il nome della funzione, perché non è necessario sottolineare il funzionamento della funzione nel suo nome (uno script). Un nome di funzione dovrebbe essere qualcosa di dolce, breve e significativo su ciò che fa la funzione. Probabilmente andrò con:
def check_running(self, script):
"""Return True if the script is running, False otherwise."""
Talvolta la nome-funzione-immaginazione è stanco da tutto il codice, ma si dovrebbe cercare comunque di fare del tuo meglio.
Per un esempio più righe, mi permetta di prendere in prestito un docstring dal google guidelines:
def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
"""Fetches rows from a Bigtable.
Retrieves rows pertaining to the given keys from the Table instance
represented by big_table. Silly things may happen if
other_silly_variable is not None.
Args:
big_table: An open Bigtable Table instance.
keys: A sequence of strings representing the key of each table row
to fetch.
other_silly_variable: Another optional variable, that has a much
longer name than the other args, and which does nothing.
Returns:
A dict mapping keys to the corresponding table row data
fetched. Each row is represented as a tuple of strings. For
example:
{'Serak': ('Rigel VII', 'Preparer'),
'Zim': ('Irk', 'Invader'),
'Lrrr': ('Omicron Persei 8', 'Emperor')}
If a key from the keys argument is missing from the dictionary,
then that row was not found in the table.
Raises:
IOError: An error occurred accessing the bigtable.Table object.
"""
Questo potrebbe essere un modo per "riassumere il suo comportamento e documentare i suoi argomenti, valore di ritorno (s), gli effetti collaterali, eccezioni sollevate e restrizioni su quando può essere chiamato (tutto se applicabile) ".
Potrebbe anche essere interessato a questo example of pypi project che è destinato a essere documentato con Sphinx.
I miei 2 centesimi: linee guida sono pensati per dare un'idea su ciò che si dovrebbe e non dovrebbe fare, ma non sono regole rigide che si devono seguire ciecamente. Quindi alla fine scegli ciò che senti di essere migliore.
vorrei chiarire qualcosa che è stato detto in un'altra risposta di colpire il massima Lunghezza linea con un docstring.
PEP8 ti dice di "Limitare tutte le linee ad un massimo di 79 caratteri" anche se alla fine ognuno fa 80.
Questo sono 80 charachters:
--------------------------------------------------------------------------------
e questo può essere un caso limite in cui un po 'lungo una frase è tutto ciò che ha realmente bisogno:
def my_long_doc_function(arg1, arg2):
"""This docstring is long, it's a little looonger than the 80 charachters
limit.
"""
è come una sola riga docstring, ovvero per i casi veramente ovvi, ma sul tuo editor (con il limite di 80 caratteri) è su più righe.