How to document a method that modifies a protected attribute with phpdoc?

Question

Hello there,

What's the best way to document a method that modifies a protected attribute with phpdoc?

For instance, what is the correct way of documenting the setVar() method below?

class Test {
  protected $variables = array();

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

Thanks in advance,

.L.

Answer 1

I usually use something akin to the following, although there is probably a better way.

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

I suppose it depends on why you are wanting to highlight that the method affects that protected attribute...

If you just want to "say" it, just say so in the description, with or without using an inline @link tag:

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

By using the inline @link, a hyperlink to the $variables documentation is generated in the method's description.

You could use the @see tag to be a standalone reference to the attribute:

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

This also makes a hyperlink to the attribute's doc, but it's more prominent by having its own tag.

If you want to create a "pointer" from the method to the attribute, use the @uses tag:

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

The @uses tag in the method here will automatically place a @usedby tag in the documentation for the $variables property... the result is a hyperlink from the method to the attribute in the method's doc, as well as a hyperlink from the attribute to the method in the attribute's doc. Think of it as analogous to the "secret passages" in the Clue board game that connect corner rooms to their opposite corner rooms.

Another intention that can be satisfied via the @uses tag is that the documentation for $variables will show a list of @usedby tags that show all methods that affect the attribute... assuming, of course, that you have been conscientious about putting @uses tags in those methods.