Comment documenter les types de paramètres de la fonction python?

Je sais que les paramètres peuvent être n'importe quel objet, mais pour la documentation, il est très important de préciser ce que vous attendez.

Première est de savoir comment spécifier un paramètre de type de ces ci-dessous?

str (ou utilisez String ou string?)
int
list
dict
function()
tuple
objet instance de la classe MyClass

Deuxième, comment spécifier les paramètres qui peuvent être de plusieurs types, comme une fonction qui permet de gérer un seul paramètre qui peut être int ou str?

Veuillez utiliser l'exemple ci-dessous pour illustrer la syntaxe nécessaire pour documenter cette avec votre proposition de solution. L'esprit qu'il est souhaitable d'être en mesure de référence de lien hypertexte à "l'Image" de la classe de l'intérieur de la documentation.

def myMethod(self, name, image):
    """
    Does something ...

    name String: name of the image
    image Image: instance of Image Class or a string indicating the filename.

    Return True if operation succeeded or False.
    """
    return True

Remarque, vous êtes les bienvenus à suggérer l'utilisation d'un outil de documentation (sphinx, oxygène, ...) tant qu'il est en mesure de traiter avec les exigences.

Mise à jour:

Il semble qu'il y a une sorte de soutien pour la documentation des types de paramètres dans doxygen. général. Le code ci-dessous fonctionne, mais qui ajoute un ennuyeux $ pour le param name (parce qu'il a été initialement faite pour php).

    @param str $arg description
    @param str|int $arg description

source d'informationauteur sorin

doxygen python

Il ya une meilleure façon. Nous utilisons

def my_method(x, y):
    """
    my_method description

    @type x: int
    @param x: An integer

    @type y: int|string
    @param y: An integer or string

    @rtype: string
    @return: Returns a sentence with your variables in it
    """

    return "Hello World! %s, %s" % (x,y)

Que c'est. Dans le PyCharm IDE cela aide beaucoup. Il fonctionne comme un charme 😉

Vous avez besoin d'ajouter un point d'exclamation au début de l'Python docstring pour Doxygen pour l'analyser correctement.

def myMethod(self, name, image):
    """!
    Does something ...

    @param name String: name of the image
    @param image Image: instance of Image Class or a string indicating the filename.

    @return Return True if operation succeeded or False.
    """
    return True

Si à l'aide de Python 3, vous pouvez utiliser la fonction annotations décrit dans PEP 3107.

def compile(
   source: "something compilable",
   filename: "where the compilable thing comes from",
   mode: "is this a single statement or a suite?"):

Voir aussi définitions de fonction.

1

Doxygen est idéal pour le C++, mais si vous travaillez avec la plupart de code python, vous devriez donner sphinx un essai. Si vous choisissez sphinx puis tout ce que vous devez faire est de suivre pep8.
0

Yup, @docu est de droite c'est (à mon humble avis la meilleure façon de combiner les deux systèmes de documentation plus ou moins transparente. Si, d'autre part, vous aussi vous voulez faire quelque chose comme mettre du texte sur la doxygen-générer un index de la page, vous pouvez ajouter
```
##
# @mainpage (Sub)Heading for the doxygen-generated index page
# Text that goes right onto the doxygen-generated index page
```
quelque part au début de votre code Python.

En d'autres termes, où doxygen ne s'attend pas à Python commentaires, utiliser ## pour alerter qu'il y a des balises pour elle. Où il attend Python commentaires (par exemple au début de ses fonctions ou de classes), l'utilisation """!.
0

Dit que j'avais poster cette petite friandise ici depuis l'IDÉE m'a montré ce qui était possible, et je n'ai jamais dit ni lire à ce sujet.
```
>>> def test( arg: bool = False ) -> None: print( arg )

>>> test(10)
10
```
Lorsque vous tapez test(en attente du doc-bulle apparaît avec (arg: bool=False) -> None Qui était quelque chose que je ne pensais qu'à Visual Studio n'.

Ce n'est pas exactement doxygen matériau, mais il est bon pour la documentation paramètre-types pour les personnes à l'aide de votre code.

Vous devez vous connecter pour publier un commentaire.