Revert "docs(ajax): amélioration de la documentation PHPDoc"

[Salvialf]

Reverts #3004

[pifou25]

Bonjour,
C'est dommage, je comprends qu'il faut mettre les commentaires et phpdoc en anglais, c'est plus universel et cohérent avec l'existant, mais il n'y a jamais "trop" de doc, ici il n'y en avait pas donc cette PR comble ce manque. Supprimer les TODO et "évolutions possibles" éventuellement si c'était le problème ?

[Salvialf]

Bonjour @pifou25,

Il ne faut pas oublier que nous développons le core quotidiennement, il n'est pas imaginable de devoir dérouler des centaines de lignes de commentaires au quotidien sur chaque fichier.

Il y a tellement de raisons en sus: la phpDoc n'a pas vocation à apprendre à développer, la roadmap n'a pas à y apparaitre, elle est générée automatiquement pour les fonctions typées (ce que les évolutions de PHP obligent de + en +) dont le nom est explicite, etc...

[pifou25]

Ha, je suis bien d'accord avec toi que les classes du core sont beaucoup trop grosses, certaines dépassent les 3000 lignes c'est juste énorme! Pour celles-ci il faudrait envisager de les diviser avant de les documenter (?)
Mais celle-ci est justement un bon exemple pour initier la phpdoc puisque c'est une toute petite classe :)
Je suis d'accord aussi sur le fait de virer les TOTO et autres éléments de roadmap oui, mais après ? une fois ce nettoyage fait, on ne doit pas être loin d'une phpdoc automatiquement générée je supose ;)

[kwizer15]

J'avais bien précisé dans la MR d'origine que c'était une proposition ouverte à toutes discussions.
J'ai fais le choix du français parce qu'on constate que ce sont majoritairement des devs français qui contribuent. On peut complètement switcher en anglais si besoin.

Concernant les "todo" ce n'est pas une roadmap mais bien des propositions d'évolution qui pouvaient être discuter dans la MR et potentiellement donner lieu a de nouvelles issues si une décision était prise.

Je trouve dommage que celle-ci ai été mergé "à la va vite".
Je trouve tout autant dommage d'avoir un MR de revert sans explication.

[Salvialf]

une fois ce nettoyage fait, on ne doit pas être loin d'une phpdoc automatiquement générée je supose ;)

Je trouve dommage que celle-ci ai été mergé "à la va vite".
Je trouve tout autant dommage d'avoir un MR de revert sans explication.

Nous avons, semble t-il, sensiblement la même vision d'ensemble...

@kwizer15 tu es sur le forum? Pourquoi pas ouvrir un sujet dans la section développeur pour en discuter entre développeurs, qu'en pensez-vous? J'interviendrais volontiers si vous le souhaitez.

[kwizer15]

@kwizer15 tu es sur le forum? Pourquoi pas ouvrir un sujet dans la section développeur pour en discuter entre développeurs, qu'en pensez-vous? J'interviendrais volontiers si vous le souhaitez.

@Salvialf Je viens de me créer un compte sur le forum, mais je n’ai pas les droits pour créer ou répondre à un sujet sur cette partie du forum.
@pifou25 avait déjà ouvert un post sur ce sujet il y a quelque temps : https://community.jeedom.com/t/aide-phpdoc-du-core/63287
Je ne sais pas s’il serait plus judicieux de repartir d’un nouveau post ou de celui-ci.

[Salvialf]

je n’ai pas les droits pour créer ou répondre à un sujet sur cette partie du forum.

@kwizer15 je t'ai passé dans le groupe développeurs ça devrait être bon.

[kwizer15]

Merci @Salvialf , discussion ouverte ici -> https://community.jeedom.com/t/aide-phpdoc-du-core/63287/8

J’aurai toutefois quelques remarques vis à vis de ton premier commentaire :

Il ne faut pas oublier que nous développons le core quotidiennement, il n'est pas imaginable de devoir dérouler des centaines de lignes de commentaires au quotidien sur chaque fichier.

Il y a tellement de raisons en sus: la phpDoc n'a pas vocation à apprendre à développer, la roadmap n'a pas à y apparaitre, elle est générée automatiquement pour les fonctions typées (ce que les évolutions de PHP obligent de + en +) dont le nom est explicite, etc...

Je comprends tout à fait la crainte d'avoir du code surchargé de commentaires, mais je voulais apporter quelques précisions techniques sur ce point.
Concernant la lisibilité du code au quotidien, la plupart des IDE modernes comme PHPStorm gèrent très bien le repli de code (code folding). D'ailleurs, nous avons déjà ces gros blocs de licence GPL en haut de la plupart des fichiers qui se replient automatiquement. La PHPDoc ne serait donc pas plus gênante.
Pour ce qui est du typage, je suis d'accord qu'avec PHP moderne, beaucoup d'éléments peuvent être déduits. Cependant, ajouter des types stricts représente souvent un risque de BC break que l’on veux forcément éviter. Une PHPDoc bien structurée peut justement nous aider pour effectuer la transition :

• On documente les types actuellement utilisés
• Les développeurs de plugins ont une meilleure visibilité
• Les IDE peuvent fournir de l'autocomplétion sans risque de casser quoi que ce soit
• On prépare le terrain pour du typage strict quand ce sera pertinent

D'ailleurs, on pourrait explorer l'utilisation d'outils comme PHPStan. Ça nous aiderait à détecter les incohérences de typage et prévenir certains bugs, tout en s'appuyant sur la PHPDoc existante.
Qu’en penses-tu ? Je suis vraiment ouvert à toute suggestion pour trouver le bon équilibre - l'idée n'est pas d'avoir de la doc pour de la doc, mais d'aider les développeurs (core et plugins) à mieux comprendre et utiliser le code.