2025.39 changes

documentation/11-code-documentation.md

@@ -70,14 +70,14 @@ récupèrent automatiquement la **documentation de leur classe**.
 
 ## Qu'est-ce qu'on met ?
 
-Pour documenter, par exemple, un module, il y a deux façons de faire :
+Pour appliquer une documentation à n'importe quel élément, il y a deux façons générales de procéder :
 
-1. Si votre documentation tient en une phrase courte.
-2. Si votre documentation va contenir davantage de texte.
+1. Votre documentation consiste en un court résumé.
+2. Votre documentation rentre dans le détail.
 
 ----
 
-### Documentation super courte
+### Phrase de résumé succinte
 
 Vous pouvez considérer qu'une seule petite phrase peut servir à décrire votre module :
 
@@ -87,19 +87,19 @@ Vous pouvez considérer qu'une seule petite phrase peut servir à décrire votre
 
 ----
 
-### Documentation plus longue
+### Documentation détaillée
 
 ```python {.numberLines}
 """
 Traitement des données d'épuration des eaux.
 
 Paragraphes de description, d'explication du contenu du module.
-Possibilité d'ajouter des sections, des exemples, soyez exhaustifs si vous le souhaitez !
+Possibilité d'ajouter des sections, des exemples, soyez exhaustifs si vous le souhaitez !
 """
 ```
 
 - Une phrase courte de résumé, sur sa propre ligne.
-- Une ligne vide.
+- **Une ligne vide**.
 - Le corps de la documentation.
 
 ----
@@ -127,11 +127,13 @@ pdoc [nom du module ou nom du script python]  # lance un serveur pour tester
 
 ----
 
-## Bonus : Donner des indications sur le type des variables et arguments
+## Extra : Donner des indications sur le type des variables et arguments
 
 Depuis Python 3.5 (fin 2015), le langage propose un moyen d'indiquer aux développeurs, le type attendu de variables et d'arguments de fonctions.
 
-**Attention cependant** : les indications en question n'ont aucune incidence sur l'exécution du code, c'est-à-dire que l'interpréteur les ignore. Par contre, les développeurs et les environnements de développement, eux, peuvent se servir de ces indications pour proposer de l'autocomplétion dans certains cas.
+**Attention cependant** : les indications en question n'ont aucun effet sur l'exécution du code, c'est-à-dire que l'interpréteur les ignore. 
+Par contre, les développeurs et les environnements de développement, eux, peuvent se servir de ces indications pour proposer de 
+l'autocomplétion ou avertir d'un mauvais usage dans certains cas.
 
 ----
 
@@ -160,7 +162,7 @@ variable: Optional[int] = None  # on attend `None` ou un entier
 multi_types: Union[int, float] = 25  # on attend un entier ou float
 collection: list[str] = []  # ne fonctionne que dans Python 3.9+
 shapeshifter: Any = []  # tout et n'importe quoi, explicitement
-finite_values: Literal["Monday", "Tuesday"] = "Monday"  # Valeurs finies
+finite_values: Literal["Monday", "Tuesday"] = "Monday"  # Valeurs littérales fixes
 function_reference: Callable = range  # on attend une fonction
 ```