Documentation de Python standard pour docstring

Question

Actuellement, je suis débutant en python et j'ai un fort PHP arrière-plan et en PHP, j'ai pris l'habitude de l'utiliser javadoc documentation du modèle. Je me demandais si l' javadoc a toute sa place comme l' docstring documentation en python. Je me demandais si quelque chose comme cela était trop élaboré pour s'adapter à l'état d'esprit Python ou j'essaie d'être aussi concis que possible :

"""
replaces template place holder with values

@param string timestamp     formatted date to display
@param string priority      priority number
@param string priority_name priority name
@param string message       message to display

@return string formatted string
"""

Et si je suis un peu trop exhaustive devrais-je aller avec quelque chose comme ceci à la place (où la plupart de la documentation n'est pas imprimée à travers l' __doc__ (méthode):

# replaces template place holder with values
#    
# @param string timestamp     formatted date to display
# @param string priority      priority number
# @param string priority_name priority name
# @param string message       message to display
#    
# @return string formatted string

def format(self, timestamp = '', priority = '', priority_name = '', message = ''):
    """
    replaces template place holder with values
    """
    values = {'%timestamp%' : timestamp,
              '%priorityName%' : priority_name,
              '%priority%' : priority,
              '%message%' : message}

    return self.__pattern.format(**values)

Merci

Answer 1

Jetez un oeil à la reStructuredText (aussi connu comme "repos"), qui est un texte en clair/docstring format de balisage, et probablement le plus populaire dans le Python monde. Et vous devriez certainement regarder Sphinx, un outil pour générer la documentation de reStructuredText (utilisé pour les eg. la documentation Python lui-même). Sphinx inclut la possibilité d'extraire de la documentation de la docstrings dans votre code (voir le sphinx.ext.autodoc), et reconnaît reste listes de champs à la suite de certaines conventions. Cela a probablement devenir (ou est devenu) le moyen le plus populaire pour le faire.

Votre exemple pourrait ressembler à ce qui suit:

"""replaces template place holder with values

:param timestamp: formatted date to display
:param priority: priority number
:param priority_name: priority name
:param message: message to display
:returns: formatted string
"""

Ou prolongé avec des informations de type:

"""replaces template place holder with values

:param timestamp: formatted date to display
:type timestamp: str or unicode
:param priority: priority number
:type priority: str or unicode
:param priority_name: priority name
:type priority_name: str or unicode
:param message: message to display
:type message: str or unicode
:returns: formatted string
:rtype: str or unicode
"""

Answer 2

La norme pour les chaînes de documentation python est décrite dans Python Enhancement proposition 257.

Le commentaire approprié pour votre méthode serait quelque chose comme

Answer 3

Jetez un oeil à la Documentation de Python, une page « destinée aux auteurs et auteurs potentiels de la documentation de Python. »

En bref, reStructuredText est ce qui est utilisé pour documenter les Python lui-même. Le guide du développeur contient un apprêt reste, style guide et conseils généraux pour l’écriture de bonne documentation.