Comment documenter une méthode qui modifie un attribut protégé avec phpdoc?

Question

Quelle est la meilleure façon de documenter une méthode qui modifie un attribut protégé avec phpdoc?

Par exemple, quelle est la manière correcte de documenter la méthode setVar() ci-dessous?

class Test { 
    protected $variables = array(); 

    public function setVar($name, $value) { 
    $this->$variables[$name] = $value; 
    } 
} 

Merci à l'avance,

.L.

Answer 1

J'utilise habituellement quelque chose de semblable à ce qui suit, bien qu'il y ait probablement un meilleur moyen.

class Test { 
    protected $variables = array(); 

//** 
    * Setter for $this->variables 
    * 
    * @var string 
    * @var string 
    * @returns void 
    */ 
    public function setVar($name, $value) { 
    $this->$variables[$name] = $value; 
    } 
} 

Answer 2

Je suppose que cela dépend pourquoi vous êtes désireux de mettre en évidence que la méthode affecte cet attribut protégé ...

Si vous voulez juste « dire », juste le dire dans la description , avec ou sans l'aide d'une balise @link en ligne:

/** 
* Setter for $variables or {@link Test::$variables} 
* ... 

en utilisant le @link en ligne, un lien hypertexte vers les variables $ la documentation est générée dans la description de la méthode.

Vous pouvez utiliser la balise @see être une référence autonome à l'attribut:

/** 
* Setter 
* @see Test::$variables 
* ... 

Ceci fait également un hyperlien vers le doc de l'attribut, mais il est plus important en ayant sa propre étiquette.

Si vous voulez créer un « pointeur » de la méthode à l'attribut, utilisez la balise @uses:

/** 
* Setter 
* @uses Test::$variables 
* ... 

La balise @uses dans la méthode ici placera automatiquement une étiquette @usedby dans la documentation pour la propriété $ variables ... le résultat est un lien hypertexte de la méthode à l'attribut dans le doc de la méthode, ainsi qu'un lien hypertexte de l'attribut à la méthode dans le document de l'attribut. Pensez-y comme analogue aux «passages secrets» du jeu de plateau Clue qui relient les pièces d'angle à leurs pièces de coin opposées.

Une autre intention qui peut être satisfaite via la balise @uses est que la documentation des variables $ montrera une liste de balises @usedby qui montrent toutes les méthodes qui affectent l'attribut ... en supposant, bien sûr, que vous avez été consciencieux à propos de mettre des balises @uses dans ces méthodes.