Наследование типа класса DocBlock

Хотя этот вопрос касается DocBlocks в целом, мой вариант использования касается PHP.

Рассмотрим следующий PHP-код:

<?php

class ParentClass {
    /**
     * Says 'hi' to the world.
     * @return ParentClass Returns itself for chaining.
     */
    public function say_hi(){
        echo 'hi';
        return $this;
    }
}

class ChildClass extends ParentClass {
    /**
     * Says 'bye' to the world.
     * @return ChildClass Returns itself for chaining.
     */
    public function say_bye(){
        echo 'bye';
        return $this;
    }
}

$c = new ChildClass;
$c->say_hi()->say_b| <- type hinting won't suggest "say_bye" here

?>

Это просто тривиальный класс с некоторой цепочкой. Расширенный класс теряет подсказку типа, потому что блок документации родительского класса использует конкретное имя класса, которое не имеет методов/свойств дочернего класса.

Предполагая, что нам нужна возможность подсказки типа (если нет, пожалуйста, оставьте этот вопрос - я не хочу здесь бесполезных аргументов), как мне это исправить?

Я придумал следующие возможности:

  • Измените стандарт PHPDoc, чтобы разрешить специальное ключевое слово
  • Добавьте лишний метод say_hi(), который вызывает родителя только для повторного объявления docblock
  • Вообще не указывайте тип возвращаемого значения, пусть IDE решает, что означает return $this; (это вообще работает?)

php javadoc phpdoc docblocks
person Christian    schedule 11.09.2012    source источник

Ответы (2)


arrow_upward
5
arrow_downward

Вы можете решить это следующим образом:

class ParentClass {
    /**
     * Says 'hi' to the world.
     * @return static
     */
    public function say_hi(){
        echo 'hi';
        return $this;
    }
}

Оператор «@return static» позволяет именно то, что вы хотите, PhpStorm прекрасно с ним работает.

person Laurent    schedule 25.10.2013

arrow_upward
2
arrow_downward

То, что вы описываете, обычно называется «беглым интерфейсом», где все методы объекта выполняют свою работу и возвращают сам объект.

Я лично не видел ни одного окончательного руководства PHPDoc о том, как это сделать. Таким образом, я не знаю, чтобы какая-либо IDE предложила средства для своей функции автозаполнения для обработки варианта использования.

Вероятный путь, который PHPDoc выберет для этого, - использовать "@return $this" в качестве соглашения для обозначения плавных методов, поскольку он соответствует самому синтаксису кода и поэтому очень ясен. Я сомневаюсь, что какие-либо IDE будут встраивать эту возможность, пока сам стандарт не будет включать этот вариант использования.

В краткосрочной перспективе я думаю, что ваш лишний "ChildClass::say_hi(){parent::say_hit();}" может заставить работать автозаполнение вашей IDE. Опять же, может, поскольку автозаполнение также распознает саму цепочку методов (например, $foo->bar()->baz()->roll()->tide();) может не существовать.

person ashnazg    schedule 12.09.2012
comment
Кажется, это нормально работает с Netbeans, хотя @return $this было бы удобно... - person Christian; 12.09.2012
comment
Оказывается, phpDocumentor 2.x распознает @return self и @return $this, чтобы понять, что метод является плавным. В результирующих документах он выделяет методы Fluent Interface, а также настраивает тип возвращаемого класса, который отображается в документе класса chlid, где он показывает унаследованный родительский метод. Как только стабильная версия 2.0.0 будет официально выпущена, я предполагаю, что IDE реализуют распознавание этого синтаксиса. Будем надеяться, что их логика автодополнения примет беглое распознавание и правильно настроит наследование методов. - person ashnazg; 13.09.2012