Le courant dominant, comme d'autres réponses l'ont déjà souligné, va probablement avec la méthode Sphinx afin que vous puissiez utiliser Sphinx pour générer ces documents sophistiqués plus tard.
Cela étant dit, personnellement, j'utilise parfois le 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 petits détails 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 déjà souligné dans un autre commentaire) sont:
- Plus important encore, les paramètres et leur documentation restent toujours ensemble, ce qui apporte les avantages suivants:
- Moins de frappe (pas besoin de répéter le nom de la variable)
- Maintenance plus facile lors du changement / suppression de variable. Il n'y aura jamais de paragraphe de doc de paramètre orphelin après avoir renommé un paramètre.
- et plus facile de trouver le commentaire manquant.
Maintenant, certains peuvent penser que ce style a l'air "moche". Mais je dirais que «laid» est un mot subjectif. Une manière plus neutre est de dire que ce style n'est pas courant, donc il peut vous sembler moins familier, donc moins confortable. Encore une fois, «confortable» est également 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 de génération de documents qui pourra également consommer un tel style en ligne. Cela stimulera l'adoption.
PS: Cette réponse est dérivée de ma propre préférence d'utiliser des commentaires en ligne chaque fois que je le juge opportun. J'utilise également le même style en ligne pour documenter un dictionnaire .