Brainstorm: How to document __get() + @property $xyz + 'calc_xyz()' pattern?

[donquixote]

A pattern I use quite a lot in PHP is this:

abstract class ContainerBase {

  private $buffer = array();

  function __get($key) {
    return array_key_exists($key, $this->buffer)
      ? $this->buffer[$key]
      : $this->buffer[$key] = $this->{'calc_' . $key}();
  }
}

/**
 * @property \X $xyz
 */
interface MyContainerInterface {}

class MyContainer extends ContainerBase implements MyContainerInterface {

  /**
   * @return \X
   * 
   * @see \MyContainerInterface::$xyz
   */
  protected function calc_xyz() {..}
}

I made it a habit to always add the @see tags to associate a method with a property. This is kind of ok, but requires too much work to set up, and the IDE has no way to validate it.

I wonder how this could be documented, to allow the IDE to

• Complain if a 'calc_*()' method for a specific property is missing, and propose to auto-create it.
• Complain if the @Property for a given 'calc_*()' method is missing, and propose to auto-create it.
• Complain if the return type of 'calc_*()' does not match the property type.
• Allow to easily navigate between the @Property and the method.
• Of course, it should be possible to use a different prefix than 'calc_'. E.g. 'get_' or 'create_'.

(Proposals in comments)

[donquixote]

A possible solution could be a @methodPrefix tag on top of the __get() method, like this:

abstract class ContainerBase {

  private $buffer = array();

  /**
   * @param string $key
   *
   * @return mixed
   *
   * @methodPrefix calc_
   */
  function __get($key) {
    return array_key_exists($key, $this->buffer)
      ? $this->buffer[$key]
      : $this->buffer[$key] = $this->{'calc_' . $key}();
  }
}

[donquixote]

Another solution could be to somehow put this into the @return tag.

abstract class ContainerBase {

  private $buffer = array();

  /**
   * @param string $key
   *
   * @return $this->{'calc_' . $key}()
   */
  function __get($key) {
    return array_key_exists($key, $this->buffer)
      ? $this->buffer[$key]
      : $this->buffer[$key] = $this->{'calc_' . $key}();
  }
}

Other ideas?

[donquixote]

Or, a smart IDE could do some code evaluation, even without any new doc tags:

• Iterate through the existing property names declared with @property.
• For each property name, evaluate __get($key) as if $key was a constant.
• This way, $function = 'calc_' . $key also becomes a constant.
• $this->$function() or $this->{'calc_' . $key}() can be evaluated like an explicit method call. The IDE can detect if a method calc_xyz() is missing, and complain - except if the class is abstract.
• The type of $v = $this->{'calc_' . $key}() can be determined by looking at the respective calc_*() method.
• Thus, the return type of __get($key) can be determined, separately for each possible value of $key. The IDE can compare this return type to the type declared in the @property tag.