[php] PHPDoc : @return void가 필요합니까?
다음과 같이 정말 필요한가요?
/**
* ...
*
* @return void
*/
반환 값이없는 메서드가 꽤 많이 있으며 주석에 이와 같은 것을 넣는 것이 정말 중복되어 보입니다. 그것을 생략하는 것이 나쁜 형태로 간주됩니까?
답변
문서가 명확하다면 그대로 두십시오. 그러나 반드시 필요한 것은 아닙니다. 전적으로 주관적인 결정입니다.
개인적으로는 생략하겠습니다.
편집
내가 수정되었습니다. 인터넷 검색을 한 후 위키 백과 페이지에 다음과 같이 표시됩니다.
@return [유형 설명]이 태그 는 생성자 또는 void 반환 유형으로 정의 된 메서드에 사용하면 안됩니다 .
phpdoc.org 웹 사이트에 따르면 :
@return 데이터 유형 설명
@return datatype1 | datatype2 설명@return 태그는 함수 또는 메서드의 반환 값을 문서화하는 데 사용됩니다. @returns는 다른 자동 다큐멘터의 태그 형식을 지원하기위한 @return의 별칭입니다.
데이터 유형은 유효한 PHP 유형 (int, string, bool 등), 반환 된 객체 유형의 클래스 이름 또는 단순히 “혼합” 이어야합니다 . 가능한 여러 반환 유형을 명시 적으로 표시하려면 공백없이 파이프로 구분하여 나열합니다 (예 : “@return int | string”). @return 태그에서 클래스 이름이 데이터 유형으로 사용되면 phpDocumentor는 해당 클래스의 문서에 대한 링크를 자동으로 생성합니다. 또한 함수가 가능한 여러 값을 반환하는 경우 | 문자, 그리고 phpDocumentor는 반환 값에서 모든 클래스 이름을 구문 분석합니다. phpDocumentor는 수정되지 않은 선택적 설명을 표시합니다.
Sooo … 그것을 바탕으로, 나는 공허함을 떠나라고 말할 것입니다. 적어도 비표준입니다.
답변
phpDocumentor에 따르면 @return void가 유효합니다.
http://www.phpdoc.org/docs/latest/guides/types.html#keywords
…이 유형은 일반적으로 메서드 또는 함수의 반환 유형을 정의 할 때만 사용됩니다. 기본 정의는이 유형으로 표시된 요소가 값을 포함하지 않으며 사용자가 검색된 값에 의존해서는 안된다는 것입니다.
예를 들면 :
/** * @return void */ function outputHello() { echo 'Hello world'; }위의 예에서는 반환 문이 지정되지 않았으므로 반환 값이 결정되지 않았습니다.
출처 : http://www.phpdoc.org/docs/latest/for-users/phpdoc/types.html ( 아카이브 페이지 ).
답변
최근에 배운 내용 때문에 답을 수정해야합니다.
@return void대신 사용 @return null하는 것은 매우 특별한 의미가 있으므로 다음 두 가지 PHP 코드 예제를 고려하십시오.
<?php
/**
* @return void
*/
function return_never() {
echo "foo";
}
/**
* @return null|string
*/
function return_sometimes() {
if ($this->condition()) {
return "foo";
}
}
첫 번째 예제에서 PHP는 NULL항상을 반환하기 때문에 실제로 반환 합니다 NULL. 그러나 반환 된 값은 함수가 무엇을했는지에 대해 아무 말도하지 않기 때문에 호출자에게 아무 소용이 없습니다. IDE는 문서화 된 정보를 사용하여 @return void개발자에게 목적이없는 반환 값이 사용됨을 나타낼 수 있습니다 .
<?php
$foo1 = return_never();
$foo2 = return_sometimes();
첫 번째 호출은 변수가 항상 포함하기 때문에 무의미하고 두 번째 호출은 NULL실제로 무언가를 포함 할 수 있습니다. 함수 호출을 조건부로 입력하면 더욱 흥미로워집니다.
<?php
if (($foo1 = return_never())) {
// Dead code
var_dump($foo1);
}
if (($foo2 = return_sometimes())) {
var_dump($foo2);
}
보시다시피 @return void사용 사례가 있으며 해당되는 경우 사용해야합니다.
또한 곧 출시 될 PHP PSR-5 표준의 일부가 될 것입니다. [1]
답변
PHP 7.1부터는 void유효한 반환 유형 이며 함수에 적용 할 수 있습니다.
나는 항상 그것을 docblock에 추가 할 것 입니다.
그것을 작성하는 또 다른 이점은 void아무 것도 반환 할 수 있지만 @return과실로 docblock에 항목 이없는 메서드 와 메서드 를 구별하는 것 입니다.
답변
PhpDocumentor 주석을 이해하고 사용하는 방법은 다음과 같습니다.
<?php
/**
* This method always returns string.
* @return string
*/
public function useCase1()
{
return 'foo';
}
/**
* This method returns 2 data types so list them both using pipeline separator.
* @return string|false
*/
public function useCase2()
{
if ($this->foo === 1) {
return 'foo';
}
return false;
}
/**
* This method performs some operation and does not return anything so no return
* annotation is needed.
*/
public function useCase3()
{
$this->doOperation();
$this->doAnotherOperation();
}
/**
* If condition passes method returns void. If condition does not pass it returns
* nothing so I think that specifying the return annotation with void is in space. :)
* @return void
*/
public function useCase4()
{
if ($this->foo === 1) {
$this->doOperation();
return;
}
$this->doAnotherOperation();
}
답변
개인적으로 여기에서 누락 된 큰 점은 함수 반환을 문서화하는 것이 중요하다는 것입니다. 현재 표준에는 절대 반환하지 않는 함수에 대한 문서가 없습니다. 따라서 반환 무효는이 함수가 실제로 반환하는 예를 말하는 방법입니다.
이 코드 블록을 고려하십시오.
<?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을 사용하면 적어도 함수가 반환한다는 것을 나타냅니다.
답변
