There needs to be a way to indicate the containing class in function docblocks without explicitly entering the name of the class

[Ibmurai]

For example when implementing a singleton:

class Singly {
    /**
     * Get the instance
     * @return Singly
     */
    public static function getInstance() {
        // Some code here...
    }
}

The @return Singly could instead be @return this, @return static or @return self or something like that.

This would be most useful for traits, which I know you are not focused on right now, but also useful in general:
What if you have a function which returns $this and extend the implementing class? Then the function really returns an instance of the extending class, and this would be really useful to be able to determine for IDE auto completion.

[Ibmurai]

Sorry,

mvriel said "since phpDocumentor2 we now support the 'self' keyword to describe: this class" on irc, just now.

[Ibmurai]

Oh I see that 'self' does not inherit - so it is not useful for traits or the situations I described, so I am reopening.

[DavidBruchmann]

I'd like to see an example how you document traits cause I thought already about the same use-case
sorry for being off-topice ;-)

[Ibmurai]

@DavidBruchmann I have this, for now:

/**
 * A generic singleton trait.
 *
 * @author Jens Riisom Schultz <ibber_of_crew42@hotmail.com>
 */
trait Singleton {
    /**
     * Get the singleton instance.
     *
     * @return static
     */
    public static function getInstance() {
        static $instance = null;

        if (!isset($instance)) {
            $instance = new self();
        }

        return $instance;
    }

    /**
     * Make the constructor private.
     *
     * @return void
     */
    private function __construct() {}
}

[DavidBruchmann]

@Ibmurai, thanks - usability for traits concerning documentation seems being still improvable.

[mvriel]

Well basically self and $this describe returning an object of the same class or the exact same instance.
You say that self does not inherit; can you give me an explicit example to help me make up my mind about it?
(p.s. I'd discourage the use of @return static since static has a different meaning than the intention)

[Ibmurai]

@mvriel Since PHP 5.3 static means the late bound self, so static would make sense.
Say you have a base singleton class which all your singletons inherit their getInstance from. That would instantiate a new static() and thus @return self or @return $this would not suffice...

[mvriel]

Still contemplating about the 'static' keyword; my biggest problem with it is that it could be considered confusing.

[Ibmurai]

I agree. It's just implemented like that, to avoid introducing a new keyword... I would probably have created a new keyword. But it is what it is...
So I still think "static" would make the most sense since PHP chose it...

On 07/07/2012, at 13.08, Mike van Rielreply@reply.github.com wrote:

Still contemplating about the 'static' keyword; my biggest problem with it is that it could be considered confusing.

---

Reply to this email directly or view it on GitHub:
#514 (comment)

[Gomes81]

Definitively static should be implemented... What are the perspectives for his implementation?... I really miss this when a child class did not implement a parent method that return an instance of the child class and not an instance of the class where the method is defined (the parent). In this case, self doesn't resolve the issue.

For example:

/**
 * Description of Model
 *
 * @author jgomes
 */
abstract class Model{
    protected $dbInstance;


    public function __construct()
    {
    $this->dbInstance = bd::getInstance();
    }


    public abstract function getTable();


    public abstract function getPKName();


    protected abstract function getCommonQuery();


    /**
     * Get all records from the model or only the ones with the passed ids.
     *
     * @param int[] $ids Optional array with all record ids we want to fetch,
     * or null to fetch them all.
     * @return static[] All founded records in the model
     */
    public static function getAll($ids = null)
    {
        $obj = new static();// this is the line that really matters
        $query = $obj->getCommonQuery();

        if( $ids !== null && is_array($ids) ){
            $query .= " WHERE {$obj->getPKName()} IN(" . implode(', ', $ids) . ")";
        }elseif( $ids !== null ){
            $query .= " WHERE {$obj->getPKName()} = {$ids}";
        }

        return $obj->dbInstance->execSQL($query, get_class($obj));
    }
}


/**
 * Description of MailContact
 *
 * @author jgomes
 */
class MailContact extends Model{
    public $id = 0;
    public $nome;
    public $email;


    public function __construct()
    {
        parent::__construct();
    }


    public function getTable()
    {
        return 'mailcontact';
    }


    public function getPKName()
    {
        return 'idmailcontact';
    }


    protected function getCommonQuery()
    {
        return 'SELECT
                    id,
                    nome,
                    email
                FROM mailcontact';
    }
}

Hope this can help.

[mvriel]

This item is still under discussion; at current self and $this are implemented where both indicate the top class (and thus has a semantically meaning than the native php 'self').

@ashnazg, @cweiske and I have had a discussion regarding this on IRC whether to change this to self and static, and make these semantically equal to their PHP counterparts.
I personally dislike the 'static' keyword as it could lead to confusion though I am getting more and more swayed by the argument that PHP uses it like this and as such should phpDocumentor to follow suit. (even if I do not like it).

@ashnazg, what do you think?

[boenrobot]

What's the problem with adding it as a third alias?

[mvriel]

@boenrobot feature creep; I don't mind adding it but it needs to be well-considered. Once it is in it can never go out again