Quand devrais-je utiliser la balise @see dans mon document intégré pour les fonctions et les méthodes de classe?
Il est écrit "Référence à une fonction, une méthode ou une classe sur laquelle on se fie énormément." à https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/#1-functions-class-methods .
D'accord. Mais si j'ai une fonction, cela signifie toujours que quelque chose l'utilise, car il n'est pas nécessaire d'écrire une fonction si elle n'est pas utilisée. Et que veut dire "très sollicité"? Cela signifie que si je supprime une fonction, la fonction dépendante ne fonctionnera pas correctement? Toujours chaque fonction, et toujours je devrais toujours utiliser la balise "@see".
Si je regarde le code WP ou WC, la balise "@see" est utilisée de manière aléatoire.
Je ne comprends vraiment pas. S'il vous plaît, expliquez. Quand devrais-je utiliser la balise "@see"?
La balise "@see" est utilisée de manière aléatoire
Rien d'étonnant à ce que toute documentation à la fin dépende de la décision du programmeur de déterminer ce qui mérite d'être documenté et comment.
La documentation en général ne doit pas être une description verbale du code, sauf si le code est extrêmement simple, mais ajouter un résumé estival de ce que le code fait et pourquoi. Par conséquent, il est trivial que les fonctions utilisées dans le code ne méritent pas d'être référencées dans @see car elles le sont déjà. Vous devriez l'utiliser quand il y a une certaine dépendance sur le fonctionnement d'une fonction différente, soit parce que vous en obtenez une entrée sous une forme ou une autre, soit parce qu'elle va traiter votre sortie (définitions très détendues d'entrée et de sortie ici).
Donc, il s'agit d'un jugement. Serez-vous capable de comprendre pourquoi la fonction A ignore tout de la fonction B? Si c'est le cas, le @see n'est pas nécessaire, mais si par exemple A définit une variable globale à utiliser par B, les deux devraient probablement contenir une référence l'un à l'autre (évidemment, un bon code ne devrait tout simplement pas avoir ce genre de choses;)).