Comment documenter une méthode avec paramètre(s) ?

Question

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 comme

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

Answer 1

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 recommande de vous familiariser avec le Balisage Sphinx car il est largement utilisé et est en train de devenir la norme de facto pour la documentation des projets Python, notamment en raison de l'excellente qualité de son contenu. readthedocs.org service. Pour paraphraser un exemple de la documentation de Sphinx sous la forme d'un extrait Python :

def send_message(sender, recipient, message_body, priority=1) -> int:
   """
   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 les documents et plus encore. Notez que la documentation de 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 \param commandes mais ils ne sont pas spécifiquement conçus pour documenter le code Python comme l'est Sphinx.

Notez qu'il existe un question similaire avec un réponse similaire ici...

Answer 2

D'après mon expérience, le conventions de la docstring numpy (superset PEP257) sont les plus répandus. suivi de conventions qui sont également prises en charge par des outils, tels que Sphinx .

Un exemple :

Parameters
----------
x : type
    Description of parameter `x`.

Answer 3

Conventions :

• PEP 257 Conventions Docstring
• PEP 287 Format de la docstring reStructuredText

Outils :

• Epydoc : Génération automatique de documentation d'API pour Python
• sphinx.ext.autodoc - Inclure la documentation à partir de docstrings
• PyCharm offre un bon support pour les docstrings.

---

Mise à jour : depuis Python 3.5, vous pouvez utiliser conseils sur le type qui est une syntaxe compacte et lisible par la 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 non ambiguë, de sorte que des outils comme PyCharm peuvent facilement en tirer parti.

Answer 4

Les chaînes de la documentation python sont forme libre vous pouvez le documenter de la manière que vous voulez.

Exemples :

def mymethod(self, foo, bars):
    """
    Does neat stuff!
    Parameters:
      foo - a foo of type FooType to bar with.
      bars - The list of bars
    """

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.

Answer 5

Si vous prévoyez d'utiliser Sphinx pour documenter votre code, il est capable de produire des documents HTML joliment formatés pour vos paramètres grâce à sa fonction "signatures". http://sphinx-doc.org/domains.html#signatures