Quelle est la méthode Pythonic pour créer des commentaires informatifs dans Python 2.x?

Question

Pour plus de précisions, C# a la directive '///' qui appelle les commentaires de style super-secret qui vous permettent d'avoir de beaux commentaires intégrés dans intellisense. Java a la directive '@' qui vous permet d'avoir aussi de jolis commentaires.

Est-ce que Python a quelque chose comme ça? J'espère que cette question est assez claire, merci!

Answer 1

En python, une docstring peut être visualisée via des commandes.

class myClass: 
    """ 
     This is some documentation for the class. 
     method1() 
     method2() 
    """ 
    def method1(p1): 
     .... 
     ... 
     ... 
    def method2(): 
     ... 
     ... 

v = myClass 

alors vous pouvez voir la docstring en utilisant soit

v.__doc__ 

ou

help(myClass) 

Answer 2

Ils sont appelés docstrings en Python. See the documentation.

Une caractéristique intéressante sont les exemples de code (explained here). Ils permettent de mettre le code dans la documentation:

>>> 1 + 1 
2 
>>> 

Bien que cela ne ressemble pas beaucoup, il est un outil qui permet de numériser les docstrings pour de tels motifs et exécuter ce code comme tests unitaires. Cela fait en sorte que la documentation Python ne soit pas périmée (contrairement à d'autres langages).

Answer 3

Python ne dispose pas de "l'outil" pour générer de la documentation. Un des outils disponibles que je peux recommander est epydoc. Il prend en charge des directives telles que @type, @param, @rtype, @returns et @raises. Le site a également quelques exemples.

Answer 4

La convention est bien documentée dans PEP 257.

Pour récapituler, ajoutez des chaînes à guillemets simples comme première instruction dans n'importe quelle classe ou fonction.

Il y a aussi de l'histoire qui vaut la peine d'être lue si vous avez le temps en PEP 256.

Answer 5

que d'autres personnes a souligné en Python la ressource que vous recherchez est appelée chaîne de doc. autres personnes ont suggéré de lire la documentation, alibeit je suggère de regarder ce lien

Sphinx Project, c'est un système comme le château de sable que vous aider à la construction et à la documentation élaborée, cette documentation peut être construite à partir de doc string, mais n'est pas obligatoire.

espérons que cette aide