Python_-quelques-bases.md

@@ -155,15 +155,23 @@ def ma_fonction(param1, param2, param3):
 ``` 
 
 Cas particulier des **méthodes**, avec le mot-clé **self**pour renvoyer à l'instance courante (attention, tout autre mot fait l'affaire, dont si vous l'oubliez le premier nom fourni fera office de "self" !).
-On remarque que dans le cas de la fonction **__init__** qui initialise l'instance, les **attributs** n'ont pas forcément le même nom que les paramètres, et peuvent d'ailleurs être en nombre différent !
+On remarque que dans le cas de la fonction **`__init__`** qui initialise l'instance, les **attributs** n'ont pas forcément le même nom que les paramètres, et peuvent d'ailleurs être en nombre différent !
 
 ``` python
 class MonObjet:
+    """ Cette classe est là car il en faut une ; un docstring au format google
+
+    Attributes:
+        class_attribute (str): (class attribute) parce que j'ai envie de mettre un argument de classe
+        param1 (float): un attribut d'instance
+        somme (float): somme de deux valeurs fournies dans le __init__
+    """
+    class_attribute = "la classe, cet attribut"
     def __init__ (param1, param2, param3):
         self.param1 = param1
         self.somme = param2 + param3
     def ma_methode(self, a, b):ab: 
-         """J'ajoute a et b à self.somme.
+         """ docstring au format PEP : J'ajoute a et b à self.somme.
          :param a : un truc à ajouter
          :type a : entier
          :param b : un autre truc à ajouter
@@ -192,7 +200,7 @@ machin = MonObjet(4,5,6)
 bidule = machin.ma_methode(1,2)
 
 Un point de vocabulaire : **paramètres** et **arguments**
-En Python vous trouverez ces deux termes. Pour la documentation des fonctions (les "docstrings"), qui est une bonne pratique [recommandée dans les PEPs](https://peps.python.org/pep-0257/), selon le format suivi va vous demander de les définir comme `:param nom_variable: ` ([Sphinx](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html) ) 
+En Python vous trouverez ces deux termes. Pour la documentation des fonctions (les "docstrings"), qui est une bonne pratique [recommandée dans les PEPs](https://peps.python.org/pep-0257/), sphinx  "paramètres"  de les définir comme `:param nom_variable: ` ([Sphinx](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html) ) tandis que le format Google utilise Argas...  Attributes:
 En théorie, les **paramètres** sont ce qui est **déclaré** dans la fonction, entre les parenthèses, et les **arguments** sont ce qui est passé lors de l'**appel** de la fonction.
 Donc, ici a et b seraient les paramètres de `ma_methode` et 1,2 seraient les arguments passés lors de l'appel.
 La méthode `ma_methode` renvoie ici un nombre calculé par la fonction, qui est également décrit dans la docstring.
@@ -200,6 +208,10 @@ La méthode `ma_methode` renvoie ici un nombre calculé par la fonction, qui est
 :bulb: Petite astuce sous l'IDE PyCharm quand on appelle une fonction:
 >  quand le curseur est positionné entre les parenthèses, **Ctrl+P** fait apparaître la liste des paramètres attendus.
 
+:bulb: Votre IDE, convenablement configuré, peut créer automatiquement la docstring, surtout si vous utilisez les annotations.
+`def ma_fonction(param1:str, param2:int, param3:float) -> float:`
+Attention, les **annotations** sont des indications ; votre IDE ou votre débuggueur peuvent détecter des anomalies, mais une définition incorrecte d'annotation n'empêchera pas vos code de tourner, par contre cela peut compliquer le travail de quelqu'un qui essaierait de comprendre le code...
+
 La manière de définir et d'ordonner les paramètres est décrite dans le point **f** ci-dessous