Voici un exemple [ https://wall.deblan.org/x1916/php/1/ ].

Dans le constructeur, l'exception de setBar est propagée ; que faut-il mettre dans le @throws ? C'est mieux de recopier la condition de l'exception, quitte à avoir redondance entre le @throws du constructeur et de setBar ?

Sinon c'est correct de mettre un @see self::setBar() et de ne pas mettre de @throws sur le constructeur ?

Je me pose une question similaire pour les description de variables ; ici j'ai mis la description de $bar à la déclaration de la variable membre, mais dans les @param (et @return) j'ai juste mis le type... ça passe de faire ça où c'est mieux de recopier la description à chaque fois ?

Ton @throws sur le constructeur n'a pas de sens, ce qui n'est pas le cas pour setBar.

Ton attribut $bar et le paramètre $bar peuvent avoir un sens différent, tu devrais coller une description sur les deux. Btw, tu te trouves dans un contexte de setter classique donc tu peux t'en passer.

D'accord, merci. Pourtant le constructeur utilise setBar sans modifier la valeur et sans try/catch, si je passe une valeur non valide au constructeur (sans explicitement appeler setBar), j'aurai une exception mais elle ne sera pas documentée... donc en PHPDoc on ne documente que les exceptions "directes", pas celles qui sont volontairement propagées ?

Dans le cas où l'attribut et le paramètre ont le même sens, y'a pas une convention pour un genre de @see inline (genre @param integer $bar self::$bar), plutôt que de c/c la description ?

Imagine que tu appelles setBar() 1000x dans 1000 méthodes différentes, sans try/catch, tu vas documenter l'exception levée par setBar dans les 1000 méthodes ? La réponse est non

Je n'ai pas de réponse pour la seconde question.

J'avoue que ce serait pas viable de documenter toutes les exceptions comme ça.

Y'a pas l'air d'avoir de notation spécifique pour reprendre une description... je me contenterai d'une convention personnelle (@param integer $bar self::$bar), merci de tes réponses.