Docstrings - une ligne vs de ligne multiples

La règle générale que vous cherchez est de droit dans PEP257 dans ce que vous avez cité, peut-être vous avez juste besoin de le voir en action.

Votre fonction est un bon candidat pour une ligne de docstring ("vraiment des cas évidents"):

def script_running(self, script):
    """Check if the script is running."""

Habituellement, si vous dites qu'une fonction est de vérifier quelque chose, il signifie qu'il va revenir True ou False, mais si vous le souhaitez, vous pourriez être plus précis:

def script_running(self, script):
    """Return True if the script is running, False otherwise."""

Une fois de plus dans une seule ligne.

Je ne serais probablement aussi changer le nom de votre fonction, car il n'y a pas besoin de mettre l'accent sur ce que la fonction travaille en son nom (un script). Un nom de fonction doit être quelque chose de doux, court et significatif sur quoi la fonction. Probablement, je vais aller avec:

def check_running(self, script):
    """Return True if the script is running, False otherwise."""

Parfois la fonction-nom-de l'imagination est fatigué par tout le codage, mais vous devriez quand même essayer de faire de votre mieux.

Pour une multiligne exemple, permettez-moi d'emprunter une docstring de la les directives de google:

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.
    """

Ce pourrait être une manière de "résumer son comportement et de documenter ses arguments, la valeur de retour(s), les effets secondaires, les exceptions soulevées, et les restrictions sur le moment où il peut être appelé (si applicable)".

Vous pourriez aussi être intéressé à regarder ce exemple de projet pypi que c'est censé être documenté avec des Sphinx.

Mes 2 cents: lignes Directrices sont destinés à vous donner une idée de ce que vous devriez et ne devriez pas le faire, mais ils ne sont pas des règles strictes que vous avez à suivre aveuglément. Ainsi, à la fin de choisir ce que vous sentez être mieux.

---

Je voudrais quelque chose de clair qui est dit dans une autre réponse à frapper la Maximum de la Longueur de la Ligne avec une docstring.

PEP8 vous dit de "Limite de toutes les lignes jusqu'à un maximum de 79 caractères" même si à la fin tout le monde ne 80.

Ce sont 80 charachters:

--------------------------------------------------------------------------------

Et ce peut être un cas limite où un peu plus long qu'une phrase est tout ce dont vous avez besoin:

def my_long_doc_function(arg1, arg2):
    """This docstring is long, it's a little looonger than the 80 charachters
    limit.

    """

Est comme une ligne de docstring, ce qui signifie que est vraiment un cas évident, mais sur votre éditeur de texte (avec le 80 caractere limite) est sur plusieurs lignes.

OriginalL'auteur Rik Poggi