Add developer documentation for PHPDoc

fr_FR/dev/index.md

@@ -17,6 +17,7 @@ Un [compte développeur](https://blog.jeedom.com/jeedom-partenaire/) est nécess
 - [Transfert de plugin](/fr_FR/dev/transfert)
 
 - [Développement js et Core 4.4 +](/fr_FR/dev/corejs/index)
+- [Développement PHP](/fr_FR/dev/php/index)
 
 ### Évolutions du Core et adaptations des plugins
 

fr_FR/dev/php/index.md

@@ -0,0 +1,3 @@
+# Développement PHP
+
+- [Standards de Documentation PHP pour le Core Jeedom](/fr_FR/dev/php/phpdoc)

fr_FR/dev/php/phpdoc.md

@@ -0,0 +1,86 @@
+# Standards de Documentation PHP pour le Core Jeedom
+
+## Règles Générales
+
+1. **Langue**
+   - Toute la documentation doit être rédigée en anglais
+   - Cela inclut les descriptions de classes, de méthodes et de paramètres
+
+2. **Portée de la Documentation**
+   - La PHPDoc doit être concise et ne pas gêner la lisibilité du code
+   - Se concentrer sur la documentation du comportement actuel et des types
+   - Éviter les détails d'implémentation ou les explications trop longues
+
+3. **Documentation des Classes**
+   - Description brève de l'objectif de la classe (1-2 phrases)
+   - Exemple simple d'utilisation si la classe est couramment utilisée par les développeurs de plugins
+   - Références croisées vers les classes liées avec `@see` quand pertinent
+
+4. **Documentation des Méthodes**
+   - Description brève (1-2 phrases maximum)
+   - Si le nom de la méthode est explicite, la description peut être omise
+   - Documentation obligatoire de tous les paramètres et types de retour avec `@param` et `@return`
+   - Documentation des exceptions avec `@throws` le cas échéant
+
+5. **Documentation des Types**
+   - Utiliser `@param` et `@return` pour les indications de type quand le typage strict n'est pas possible
+   - Utiliser `@var` pour la documentation des types de propriétés quand nécessaire
+   - Les types doivent refléter l'usage actuel, pas l'usage futur idéal
+   - Pour les enums, utiliser la syntaxe union de littéraux :
+     ```php
+     /** @var string 'stop'|'starting'|'run'|'stoping'|'error' */
+     ```
+   - Pour les tableaux :
+     - Éviter le simple `array` quand le type des éléments est connu
+     - Pour les listes simples, privilégier la notation `string[]`
+     - Pour les tableaux associatifs avec clés significatives, utiliser `array<int, string>`
+     - Pour les structures complexes (comme du JSON encodé), préférer documenter le format via `@link` plutôt qu'une description détaillée du tableau
+
+6. **Éléments Interdits**
+   - Pas de TODOs ou d'éléments de roadmap
+   - Pas de propositions d'évolution ou de changements futurs
+   - Pas d'exemples de code longs (faire un lien vers la documentation développeur à la place)
+   - Pas de détails d'implémentation ou de notes internes
+
+7. **Exemples de Code**
+   - Limités à un exemple court par classe quand nécessaire
+   - Doivent être concis et démontrer uniquement l'usage basique
+   - Les exemples complexes doivent être liés à la documentation développeur
+
+8. **Liens et Références**
+   - Utiliser `@link` pour référencer la documentation externe si nécessaire
+   - Utiliser `@see` pour référencer les classes ou méthodes liées
+   - Les liens doivent principalement pointer vers la documentation développeur Jeedom
+
+## Format
+
+```php
+/**
+ * Brève description de la classe
+ *
+ * @see ClasseLiee Pour les fonctionnalités liées
+ */
+class Exemple {
+    /**
+     * Brève description de la méthode si nécessaire
+     *
+     * @param string $param Description du paramètre
+     * @return void
+     * @throws \Exception En cas d'échec
+     */
+    public function methode($param) {
+    }
+}
+```
+
+## Bonnes Pratiques Supplémentaires
+
+1. **Organisation du Code**
+    - Les blocs PHPDoc doivent être bien alignés et formatés de manière cohérente
+    - Maintenir une séparation claire entre les sections de code avec les commentaires standards de Jeedom
+    - Utiliser les espaces de manière cohérente dans la documentation
+
+2. **Maintenance**
+    - Mettre à jour la documentation lors des modifications de code
+    - Supprimer la documentation obsolète
+    - Garder la documentation synchronisée avec le comportement réel du code