web-dev-qa-db-fra.com

Utilisation de javadoc pour Python documentation

Je commence actuellement avec Python et j'ai un fort PHP fond et en PHP j'ai pris l'habitude d'utiliser javadoc en tant que modèle de documentation.

Je me demandais si javadoc avait sa place en tant que docstring documentation en Python. Quelles sont les conventions établies et/ou les guildelines officielles ici?

Par exemple. Est-ce que quelque chose comme ceci est trop élaboré pour tenir dans l'état d'esprit Python ou devrais-je essayer 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 exhaustif, devrais-je plutôt utiliser quelque chose comme ceci (où la plupart de la documentation n'est pas imprimée via le __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)
pythondocumentationjavadocdocstring
157
JF Dion

Jetez un coup d’œil au format reStructuredText (également appelé "reST"), qui est un format de balisage texte/docstring, et probablement le plus populaire dans le monde Python Et vous devriez certainement regarder Sphinx , un outil pour générer de la documentation à partir de reStructuredText (utilisé par exemple pour le Python elle-même). Sphinx permet d'extraire de la documentation. à partir des docstrings de votre code (voir sphinx.ext.autodoc ), et reconnaît reST listes de champs selon certaines conventions. Ceci est probablement devenu (ou est en train de devenir) le plus populaire façon de le faire.

Votre exemple pourrait ressembler à ceci:

"""Replaces template placeholder 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 étendu avec les informations de type:

"""Replaces template placeholder 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
"""
224
Steven

Suivez Google Python Style Guide . Notez que Sphinx peut également analyser ce format à l’aide de l’extension Napolean , qui sera fournie avec Sphinx 1.3 ( Ceci est également compatible avec PEP257 ):

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2

    Returns:
        bool: Description of return value

    """
    return True

Exemple tiré de la documentation Napolean liée ci-dessus.

Un exemple complet sur tous les types de docstrings ici .

73
confused00

La norme pour les chaînes python) est décrite dans Proposition d’amélioration Python 257 .

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

def format(...):
    """Return timestamp string with place holders replaced with values.

    Keyword arguments:
    timestamp     -- the format string (default '')
    priority      -- priority number (default '')
    priority_name -- priority name (default '')
    message       -- message to display (default '')
    """
25
srgerg

Jetez un œil à Documenting Python , une page "destinée aux auteurs et auteurs potentiels de la documentation pour Python".

En bref, reStructuredText est ce qui est utilisé pour documenter Python lui-même. Le guide du développeur contient un guide d'introduction, un guide de style et des conseils généraux pour rédiger une bonne documentation.

1
David Cain