PHPDOC : @return void 필요합니까?

StackOverflow https://stackoverflow.com/questions/2061550

  •  20-09-2019
  •  | 
  •  

문제

정말로 다음과 같은 일을해야합니까?

/**
 * ...
 * 
 * @return void
 */

리턴 값이없는 방법이 상당히 많이 있으며, 이와 같은 것을 주석에 넣는 것은 정말 중복되는 것 같습니다. 그것을 남겨 두는 것이 나쁜 형태로 간주됩니까?

도움이 되었습니까?

해결책

문서가 명확 해지면 그대로 두지 만 엄격히 필요하지 않습니다. 전적으로 주관적인 결정입니다.

개인적으로, 나는 그것을 꺼낼 것입니다.

편집하다
나는 수정했다. 약간의 인터넷 검색 후 Wikipedia 페이지 말 :

@return [유형 설명]이 태그 사용해서는 안됩니다 공극 반환 유형으로 정의 된 생성자 또는 방법의 경우.

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, PHP는 항상 돌아 오기 때문에 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]

[1] http://www.php-fig.org/psr/

PHP 7.1 기준으로 void 유효한 반환 유형입니다 그리고 ~할 수 있다 함수에 시행됩니다.

나는 할 것이다 언제나 DocBlock에 추가하십시오.

그것을 쓰는 또 다른 이점은 void 아무것도 반환 할 수 있지만 @return 태만에 의한 문서 블록의 입력.

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();
}
라이센스 : CC-BY-SA ~와 함께 속성
제휴하지 않습니다 StackOverflow
scroll top