Bonjour,
Je trouve que la meilleure doc c’est celle qui est dans le code donc les commentaires et aussi surtout la phpdoc
Pas pour l’utilisateur bien sûr, mais pour tous les développeurs (plugin ou core) on a toujours besoin de faire référence au code, et le code jeedom manque cruellement de commentaires.
J’ai fait un test, mais il faut le prendre comme il est, pour tester les balises et la génération du site: conversion des commentaires au format phpdoc, en un site statique html. Comme ce n’est qu’un test j’ai juste fait la classe eqLogic, et encore j’imagine que mes commentaires ne sont pas pertinent mais je connais mal ce code encore. https://pifou25.github.io/jeedom-core/classes/eqLogic.html
l’original pour comparaison https://doc.jeedom.com/dev/phpdoc/4.1/classes/eqLogic.html
Je l’ai généré avec phpdocumentor, par contre je patauge encore avec docker les github action et les circle-ci automatisés.
Super ça !
Une vrai doc php commentée avec des exemples serait tellement utile…
Rien que de savoir ce que l’on peut / doit passer en paramètre à une méthode …
j’ai mis le tag @package bien qu’il n’y a pas de namespace à ce jour, mais on y viendra sûrement un jour. Le tag dans phpdoc n’a aucune influence sur le code mais ça permet de ranger les classes comme avec un namespace lorsqu’il n’y en a pas.
j’utilise de plus en plus les tags @see et @uses pour faire des liens entre les différentes portions de code, c’est très pratique pour naviguer. Je crois que certains IDE prennent en compte ces tags aussi pour la navigation dans le code, si certains ont des retours ?
j’utilise aussi le tag @link pour ajouter des liens vers la doc officielle jeedom
cette classe cmd.class.php est outrageusement longue, il faudra la diviser en plein de petites du coup, les descriptions que j’ai pu mettre sont surement très approximatives, je m’en excuse, mais je découvre encore le code.
J’ai mis en place une génération automatique (avec circleci): à chaque push sur la branche phpdoc ça génère et déploie le résultat tout seul (plus d’info si ça vous intéresse?)
Pour finir, je vous invite à participer sur ma branche phpdocs pour les classes qui sont dans core/class - je ne pense pas que c’est intéressant de faire les autres fichiers.
Bon, c’est l’échec: à mon retour de vacances, je n’arrive plus à aligner ma branche sur la branche d’origine (upstream) il y a eu trop d’écart, des conflits dans tous les sens…
Vous faites comment pour gérer les merge / rebase sur des fichiers de +3000L et 50 conflits?
