Utilisation de javadoc pour la documentation Python [fermé]
je commence actuellement avec Python et j'ai un fond PHP fort et en PHP j'ai pris l'habitude d'utiliser javadoc comme modèle de documentation.
je me demandais si javadoc avait sa place comme docstring documentation en Python. Est quelque chose comme cela trop compliqué pour rentrer 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 je devrais aller avec quelque chose comme ça à la place (où la plupart de la documentation n'est pas imprimée par la méthode __doc__ )?
# 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)
4 réponses
regardez le format reStructuredText (aussi connu sous le nom de" reST"), qui est un format de markup en plaintext/docstring, et probablement le plus populaire dans le monde de Python. Et vous devriez certainement regarder Sphinx , un outil pour générer de la documentation à partir de reStructuredText (utilisé pour par exemple. la documentation Python elle-même). Sphinx inclut la possibilité d'extraire de la documentation des docstrings de votre code (voir Sphinx.ext.autodoc ), et reconnaît reST field lists suivant certaines conventions. Cela est probablement devenu (ou est en train de devenir) la façon 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 l'information 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
"""
Suivre Google Python Guide De Style . Notez que Sphinx peut également analyser ce format en utilisant l'extension Napolean , qui sera fourni avec Sphinx 1.3 (ce qui 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 cordons ici .
la norme pour les chaînes de documentation python est décrite dans Python Enhancement Proposal 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 '')
"""
regardez 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 un manuel reST primer, un guide de style et des conseils généraux pour rédiger une bonne documentation.