PHPDoc: @return, пусто необходимый?
2 ответа
Если это позволяет понять для документации, то оставьте его, но это не требуется строго необходима. Это совершенно субъективное решение.
Лично я оставил это.
Редактировать
Я стою исправлена. После небольшого густочка, страница Page Wikipedia говорит:
@return [Тип описания] Этот тег не должен использоваться для конструкторов или методов, определенных с типом возврата пустота.
Сайт phpdoc.org говорит:
@return datatype Описание
@return datatype1 | DataType2 ОписаниеТег @return используется для документирования возвращаемого значения функций или методов. @ ReTurns - псевдоним для @return для поддержки форматов тегов других автоматических документов
DataType должен быть действительным типом PHP (int, string, bool и т. Д.), имя класса для возвращаемого типа, Или просто «смешанный». Если вы хотите явно показать несколько возможных типов возврата, перечислите им трубопровод без пробелов (например, «@return int | String»). Если имя класса используется в качестве DataType в теге @return, PHPDocumentor автоматически создаст ссылку на документацию этого класса. Кроме того, если функция возвращает несколько возможных значений, отделите их с помощью | Персонаж и PhPDocumentor будут изучать любые названия классов во время возврата. PhPDocumentor отобразит дополнительное описание немодифицировано.
SOOO ... основываясь на этом, я бы сказал, оставьте пустоту. Это нестандартно, по крайней мере.
Лично, я думаю, что большая вещь, отсутствующая в этом, состоит в том, что документирование функции возвращается, вообще важно. В настоящее время стандарты не имеют никакой документации для функций, которые никогда не возвращаются.... следовательно, возврат пусто является способом сказать да, эта функция действительно на самом деле возвращается.
Рассматривают этот блок кода
<?php
/**
* @return void
*/
function return_void() {
echo "foo";
}
/**
* @return null|string
*/
function return_sometimes() {
if ($this->condition()) {
return "foo";
}
}
/**
* This function actually doesnt return at all - it kills the script
**/
function noreturn() {
//do somthing then
die(); //or exit()
}Очевидно, использование @return, по крайней мере, указывает, что функция действительно возвращается