Utilisation de javadoc pour la documentation Python [fermé]

Je débute actuellement avec Python et j'ai une solide expérience en PHP et en PHP j'ai pris l'habitude de l'utiliser javadoccomme modèle de documentation.

Je me demandais si javadoca sa place en tant que docstringdocumentation en Python. Quelles sont les conventions établies et / ou les guildes officielles ici?

Par exemple, est-ce que quelque chose comme ça est trop élaboré pour s'intégrer 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 utiliser quelque chose comme ça à la place (où la plupart de la documentation n'est pas imprimée via la __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)

Jetez un œil au format reStructuredText (également connu sous le nom de «reST»), qui est un format de balisage en clair / 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 la documentation Python elle-même). Sphinx inclut la possibilité d'extraire la documentation des docstrings dans votre code (voir sphinx.ext.autodoc ), et reconnaît les listes de champs reST suivant certaines conventions. C'est probablement devenu (ou est en train de devenir) la manière la plus populaire 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 des 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
"""

Suivez le guide de style Google Python . Notez que Sphinx peut également analyser ce format en utilisant l' extension Napolean , qui sera fournie avec Sphinx 1.3 (elle 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 napoléenne liée ci-dessus.

Un exemple complet sur tous les types de docstrings ici .

La norme pour les chaînes de documentation python est décrite dans la proposition d'amélioration de 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 '')
    """

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

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