Какой комментарий к документации PHP для объявления типа переменной является правильным?
Я искал различные руководства & Документация о том, как правильно объявлять тип переменной в документации, но, похоже, есть несколько вариантов.
3 разные возможности:
/** @var integer $sum */
/** @var $sum integer */
/* any of the above but with 1 asterisk */
Для параметров метода и переменных довольно ясно, как писать, как написано во многих различных документациях. Но что делать, если мы говорим о переменных, которых нет в функциях или в файлах View (шаблон проектирования MVC)?
На моем рабочем месте в настоящее время мы используем 2 разных программного обеспечения (NetBeans а также PhpStorm). Мы заметили, что они предоставляют разные шаблоны для объявления типов переменных в документации.
В PhpStorm:
В NetBeans:
В StackOverflow я также нашел 2 различных использования (Ответ с высоким рейтингом использует опцию NetBeans с 1 звездочкой но в другом вопросе говорится, что он перевернут, а также использует 2 звездочки).
Поскольку мы используем фреймворк Yii2, мы также посмотрели, как они пишут комментарии к документам. Они используют этот формат:
/* @var $this yii\web\View */
Последнее, что меня интересует (не так важно, как вопрос выше), нужно ли мне объявлять полный путь в комментариях или в использовании при объявлении объекта в комментариях? С полным путем это будет выглядеть так:
/** @var yii\BaseYii $object */
echo $object::createObject(1);
С полным путем это будет выглядеть так:
use yii\BaseYii;
/** @var BaseYii $object */
echo $object::createObject(1);
Мы бы хотели максимально точно следовать стандартам PHP.
Любая помощь приветствуется.
Я знаю, что этот вопрос может быть слишком широкий или же неясно, что вы спрашиваете, Я тоже буду внимательно следить за тем, как все пойдет.
Решение
То, что я обычно вижу, это то, что PSR-5 предложить:
/** @var int $sum This is a sum. */
$sum = 0;
О том, что если объявить полный путь или нет, все это правильный пример:
namespace \A\B\C;
use yii\BaseYii;
/** @var BaseYii $yii */
$yii = $factory->getApplication();
namespace \A\B\C;
/** @var \yii\BaseYii $yii */
$yii = $factory->getApplication();
namespace \A\B\C;
/** @var \ArrayObject|null $array */
$array = null;
/**
* @return \DateTime
*/
function now()
{
namespace App\Entity;
use Doctrine\ORM\Mapping as ORM;
/**
* @ORM\Entity
* @ORM\Table(name="foo")
*/
class Foo
Другие решения
На данный момент нет строгих стандартов, которым должны следовать все, хотя стоит упомянуть:
Два возможных стандарта:
Используя одну звездочку и поместив имя переменной перед типом:
/* @var $node Drupal\node\NodeInterface */
Этот формат поддерживается Eclipse, Netbeans, PHPStorm и Zend Studio.
Используя двойную звездочку и поместив имя переменной после типа:
/** @var Drupal\comment\CommentInterface $comment */
Второй метод также используется PhpDocumentor:
Синтаксис: @var [“Type”] [$element_name] [<description>]
Например: @var string $description Should contain a description
detector