Comment documenter une méthode avec paramètre (s)?
Comment documenter des méthodes avec des paramètres en utilisant les chaînes de documentation de Python?
EDIT: PEP 257 donne cet exemple:
def complex(real=0.0, imag=0.0):
"""Form a complex number.
Keyword arguments:
real -- the real part (default 0.0)
imag -- the imaginary part (default 0.0)
"""
if imag == 0.0 and real == 0.0: return complex_zero
...
Est-ce la convention utilisée par la plupart des développeurs Python?
Keyword arguments:
<parameter name> -- Definition (default value if any)
Je m'attendais à quelque chose d'un peu plus formel tel que
def complex(real=0.0, imag=0.0):
"""Form a complex number.
@param: real The real part (default 0.0)
@param: imag The imaginary part (default 0.0)
"""
if imag == 0.0 and real == 0.0: return complex_zero
...
Environnement : Python 2.7.1
D'après mon expérience, les conventions numpy docstring (PEP257 superset) sont les conventions les plus répandues suivies qui sont également prises en charge. par des outils tels que Sphinx .
Un exemple:
Parameters
----------
x : type
Description of parameter `x`.
Comme les docstrings sont de forme libre, cela dépend vraiment de ce que vous utilisez pour analyser le code afin de générer la documentation de l'API.
Je vous recommanderais de vous familiariser avec les balises Sphinx , car il est largement utilisé et devient le standard de facto pour documenter des projets Python, en partie grâce à l'excellent readthedocs.org service. Pour paraphraser un exemple à partir de la documentation Sphinx en tant que Python extrait:
def send_message(sender, recipient, message_body, priority=1):
'''
Send a message to a recipient
:param str sender: The person sending the message
:param str recipient: The recipient of the message
:param str message_body: The body of the message
:param priority: The priority of the message, can be a number 1-5
:type priority: integer or None
:return: the message id
:rtype: int
:raises ValueError: if the message_body exceeds 160 characters
:raises TypeError: if the message_body is not a basestring
'''
Ce balisage prend en charge références croisées entre documents et plus. Notez que la documentation Sphinx utilise (par exemple) :py:attr: alors que vous pouvez simplement utiliser :attr: lors de la documentation à partir du code source.
Naturellement, il existe d'autres outils pour documenter les API. Il y a le plus classique Doxygen qui utilise \paramcommandes mais celles-ci ne sont pas spécifiquement conçues pour documenter Python comme Sphinx est.
Notez qu'il y a un question similaire avec un réponse similaire ici ...
Conventions:
Outils:
- Epydoc: génération automatique de documentation API pour Python
- sphinx.ext.autodoc - Inclure la documentation à partir de docstrings
- PyCharm supporte Nice pour docstrings
Mise à jour: Depuis Python 3.5, vous pouvez utiliser indications de type , qui est une syntaxe compacte, lisible par machine:
from typing import Dict, Union
def foo(i: int, d: Dict[str, Union[str, int]]) -> int:
"""
Explanation: this function takes two arguments: `i` and `d`.
`i` is annotated simply as `int`. `d` is a dictionary with `str` keys
and values that can be either `str` or `int`.
The return type is `int`.
"""
Le principal avantage de cette syntaxe est qu’elle est définie par le langage et qu’elle est sans ambiguïté, de sorte que des outils tels que PyCharm peuvent facilement en tirer parti.
les chaînes de documentation python sont de forme libre, vous pouvez les documenter comme vous le souhaitez.
Exemples:
def mymethod(self, foo, bars):
"""
Does neat stuff!
Parameters:
foo - a foo of type FooType to bar with.
bars - The list of bars
"""
Maintenant, il existe certaines conventions, mais python n'en applique aucune. Certains projets ont leurs propres conventions. Certains outils permettant de travailler avec des docstrings suivent également des conventions spécifiques.
Si vous envisagez d'utiliser Sphinx pour documenter votre code, il est capable de produire des documents HTML bien formatés pour vos paramètres avec leur fonctionnalité 'signatures'. http://sphinx-doc.org/domains.html#signatures
Comme le soulignent d’autres réponses déjà évoquées, le grand public utilise probablement le façon Sphinx afin que vous puissiez utiliser Sphinx pour générer ces documents de fantaisie ultérieurement.
Cela étant dit, j'y vais de temps en temps avec un style de commentaire en ligne.
def complex( # Form a complex number
real=0.0, # the real part (default 0.0)
imag=0.0 # the imaginary part (default 0.0)
): # Returns a complex number.
"""Form a complex number.
I may still use the mainstream docstring notation,
if I foresee a need to use some other tools
to generate an HTML online doc later
"""
if imag == 0.0 and real == 0.0:
return complex_zero
other_code()
Un autre exemple ici, avec quelques détails minuscules documentés en ligne:
def foo( # Note that how I use the parenthesis rather than backslash "\"
# to natually break the function definition into multiple lines.
a_very_long_parameter_name,
# The "inline" text does not really have to be at same line,
# when your parameter name is very long.
# Besides, you can use this way to have multiple lines doc too.
# The one extra level indentation here natually matches the
# original Python indentation style.
#
# This parameter represents blah blah
# blah blah
# blah blah
param_b, # Some description about parameter B.
# Some more description about parameter B.
# As you probably noticed, the vertical alignment of pound sign
# is less a concern IMHO, as long as your docs are intuitively
# readable.
last_param, # As a side note, you can use an optional comma for
# your last parameter, as you can do in multi-line list
# or dict declaration.
): # So this ending parenthesis occupying its own line provides a
# perfect chance to use inline doc to document the return value,
# despite of its unhappy face appearance. :)
pass
Les avantages (comme @ mark-horvath l'a déjà souligné dans un autre commentaire) sont les suivants:
- Plus important encore, les paramètres et leur doc restent toujours ensemble, ce qui apporte les avantages suivants:
- Moins de frappe (pas besoin de répéter le nom de la variable)
- Maintenance facilitée lors du changement/suppression de la variable. Il n'y aura jamais de paragraphe de paramètre de paramètre Orphan après avoir renommé un paramètre.
- et plus facile à trouver commentaire manquant.
Maintenant, certains peuvent penser que ce style a l'air "moche". Mais je dirais que "moche" est un mot subjectif. Une manière plus neutre consiste à dire que ce style n’est pas courant, il peut donc sembler moins familier, donc moins confortable. Encore une fois, "confortable" est aussi un mot subjectif. Mais le fait est que tous les avantages décrits ci-dessus sont objectifs. Vous ne pouvez pas les atteindre si vous suivez la méthode standard.
Espérons qu'un jour dans le futur, il y aura un outil générateur de documentation pouvant également utiliser ce style inline. Cela conduira l'adoption.
PS: Cette réponse découle de ma propre préférence, qui consiste à utiliser des commentaires en ligne à tout moment. J'utilise le même style en ligne pour documenter un dictionnaire aussi.
Les docstrings ne sont utiles que dans les environnements interactifs, par exemple. the Python Shell. Lorsque vous documentez des objets qui ne seront pas utilisés de manière interactive (par exemple, des objets internes, des rappels de structure), vous pouvez également utiliser des commentaires normaux. Voici un style que j'utilise pour suspendre les commentaires en retrait les éléments, chacun sur sa propre ligne, afin que vous sachiez que le commentaire s'applique à:
def Recomputate \
(
TheRotaryGyrator,
# the rotary gyrator to operate on
Computrons,
# the computrons to perform the recomputation with
Forthwith,
# whether to recomputate forthwith or at one's leisure
) :
# recomputates the specified rotary gyrator with
# the desired computrons.
...
#end Recomputate
Vous ne pouvez pas faire ce genre de chose avec docstrings.