php/phpDoc - @return instancia de $ esta clase?

Question

¿Cómo marque un método como "devuelve una instancia de la clase actual" en mi phpDoc?

En el siguiente ejemplo mi IDE (Netbeans) verá que setSomething siempre devuelve un objeto foo.

Pero eso no es cierto si extiendo el objeto - devolverá $this, que en el segundo ejemplo es un objeto bar no un objeto foo.

class foo { 
    protected $_value = null; 

    /** 
    * Set something 
    * 
    * @param string $value the value 
    * @return foo 
    */ 
    public function setSomething($value) { 
     $this->_value = $value; 
     return $this; 
    } 
} 

$foo = new foo(); 
$out = $foo->setSomething(); 

Así fina - setSomething devuelve un foo - pero en el siguiente ejemplo, devuelve un bar ..:

class bar extends foo { 
    public function someOtherMethod(){} 
} 

$bar = new bar(); 
$out = $bar->setSomething(); 
$out->someOtherMethod(); // <-- Here, Netbeans will think $out 
         // is a foo, so doesn't see this other 
         // method in $out's code-completion 

... Sería genial para resolver esto como para mí, la finalización del código es un aumento de velocidad masivo.

¿Alguien tiene un truco ingenioso, o mejor aún, una forma adecuada de documentar esto con phpDoc?

Answer 1

Pensé que volvería a visitar esta Q, ya que me encontré con un par de cosas.

Actualmente "return $ this" no es compatible, pero hay una solicitud PhpDoc para agregar exactamente eso en v1.5:

http://pear.php.net/bugs/bug.php?id=16223

También hay una solicitud para ello en Eclipse PDT:

https://bugs.eclipse.org/bugs/show_bug.cgi?id=276082

Ambos son peticiones relativamente antiguos. No voy a entusiasmarme demasiado porque esto se implemente pronto, pero aquí va a esperar :) Mientras tanto, parece que no hay una solución adecuada para este problema.

Answer 2

Aquí es 3 trabajo en torno a: (Estos son sólo trabajan alrededor de las clases no deben ser diseñados e implementados para demandar el comportamiento de un IDE.)

Opción 1: hacer que el método someOtherMethod abstracto o vacía método en la clase foo

class foo implements ifoo { 
    protected $_value = null; 

    /** 
    * Set something 
    * 
    * @param string $value the value 
    * @return ifoo 
    */ 
    public function setSomething($value) { 
     $this->_value = $value; 
     return $this; 
    } 

    // abstract method or create empty method if you want the method to be 
    // to be optional 
    abstract function someOtherMethod(); 
} 

Opción 2:

reemplazar el método se tSomething en la clase de barra de

class bar extends foo { 
    /** 
    * 
    * @param <type> $value 
    * @return bar 
    */ 
    public function setSomething($value) { 
     return parent::setSomething($value); 
    } 

    public function someOtherMethod(){} 
} 

Opción 3: Uso interfaz

interface ifoo { 
    public function someOtherMethod(){} 
} 

class foo { 
    protected $_value = null; 

    /** 
    * Set something 
    * 
    * @param string $value the value 
    * @return ifoo 
    */ 
    public function setSomething($value) { 
     $this->_value = $value; 
     return $this; 
    } 
} 

class bar extends foo implements ifoo { 

    public function someOtherMethod(){} 
} 

Answer 3

phpDoc syntax allows for multiple types to be defined by separating them with a | character for the @return tag. Cuando extienda el class foo con class bar, debe escribir una nueva etiqueta phpDoc que tenga la clase adecuada para su @return.

Si una función devuelve foo o bar, entonces usaría @return foo|bar.

Sin embargo, en su caso solo defina @return bar para la función anulada.

Ten cuidado.

Answer 4

Actualización:

Como de Netbeans 7.4, el IDE soporta @return auto, estático, y esta (http://wiki.netbeans.org/NewAndNoteworthyNB74#Editor_2).

class foo { 
    protected $_value = null; 

    /** 
    * Set something 
    * 
    * @param string $value the value 
    * @return this 
    */ 
    public function setSomething($value) { 
     $this->_value = $value; 
     return $this; 
    } 
} 

class bar extends foo { 
    public function someOtherMethod(){} 
} 

---

respuesta anterior:

Tenemos un problema similar con el método de registro de un iterador current(). Dado que el iterador se extiende para muchas clases diferentes, no tiene sentido tener asociado un @return $class. Hemos usado la opción 2 de @ satrun77 anteriormente, pero he usado @method con cierto éxito en Netbeans.

class foo { 
    protected $_value = null; 

    /** 
    * Set something 
    * 
    * @param string $value the value 
    * @return foo 
    */ 
    public function setSomething($value) { 
     $this->_value = $value; 
     return $this; 
    } 
} 

/** 
* @method bar setSomething($value) 
*/ 
class bar extends foo { 
    public function someOtherMethod(){} 
}