Когда я должен использовать NULL в подсказках типа PHPDoc и docblocks?

Question

Я не понимаю, когда использовать null как тип при описании переменных с помощью PHPDoc. Должны ли подсказки типа описывать надежды и ожидания для внешних вызывающих абонентов, чтобы предвидеть и соблюдать, или они должны документировать все возможные типы переменной, даже если есть надежда, что это будет один очень специфический тип на практике?

Пример 1: значения по умолчанию. Следующая функция ожидает только ненулевые значения. Но если значение не передается, по умолчанию null и проверяет это явно как способ определить, было ли что-либо передано, и возвращает специальное значение для этого случая. Надеюсь, ни один внешний абонент не пропустит ничего, кроме целого числа. Должен null использоваться в @param введите, как показано ниже, или он должен только указать int так как это то, что мы хотим передать, если что-нибудь передается?

/**
 * @param int|null $bar
 */
function foo($bar = null) {
  if(is_null($bar)) { 
    return 'ABC';
  }

  return doSomething($bar);
}

Пример 2: свойства экземпляра. Мы только хотим, чтобы $ bar содержал целые числа. Тем не менее, если для bar ничего не установлено, значение PHP по умолчанию для этого свойства экземпляра равно нулю. Нужно ли учитывать это в каждом месте, где используется $ bar, с возможным нулевым типом, как показано ниже?

class Foo {
  /**
   * @var int|null
   */
  public $bar;

  /**
   * @param int|null $bar
   */
  public setBar( $bar) {
    $this->bar = $bar;
  }

  /**
   * @return int|null
   */
  public function getBar() {
    return $this->bar;
  }
}

В основном я мусор почти каждый @param а также @var декларация с |null потому что технически это может быть то значение. Но на практике это не должно быть. Должен ли я ожидать, что почти все мои типы будут содержать возможность null или если это предполагается, и я должен избегать его указания, если я не собираюсь установить или получить значение null явно?

Answer 1

На практике, я бы предпочел, чтобы теги param только перечисляли то, что вы хотите передать. Однако для возвращаемых тегов вам действительно нужно перечислить все типы, которые могут быть возвращены. Вот почему я не согласен с этими двумя.

Поскольку PHP не является строго типизированным, даже если вы говорите "только передать в int", ваш метод все равно должен убедиться, что он не передал что-то неожиданное. Просто потому, что код метода пытается обрабатывать прием других типов, вы не хотите, чтобы ваши документы сообщали пользователям: "Конечно, вы можете передать мне NULL, и я сделаю что-нибудь для вас". Вы хотите, чтобы ваши документы сказали "дай мне int, точка".

При рассмотрении возвращаемых значений вашим пользователям действительно нужно знать каждый потенциальный тип возвращаемого значения, который может вернуться из вашего метода, потому что им действительно необходимо охватить свои базы в своем коде для обработки всех типов, которые ваш метод может вернуть.

Answer 2

Да, по стандартам PHPDoc, вы должны включать null везде (если это применимо, конечно)

Смотрите здесь: http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.param.pkg.html

Тип данных должен быть допустимым типом PHP (int, string, bool и т. Д.), Именем класса для типа объекта или просто "смешанным". Кроме того, вы можете перечислить несколько типов данных для одного параметра, разделив их с помощью канала (например, "@param int|string $p1"). Вы можете задокументировать перечисленные параметры или любые необязательные параметры, которые будут проанализированы стандартными функциями PHP func_num_args()/get_func_arg(). Рекомендуемый формат имени для параметров, перечисленных с помощью func_get_arg(): $paramname, если есть только один параметр $paramname,... если количество параметров не ограничено