[php] 상수에 대한 PHPDocs를 작성하는 올바른 방법은 무엇입니까?

Program / 글쓴이

이 코드가 있습니다.

/**
 * Days to parse
 * @var int
 */
const DAYS_TO_PARSE = 10;
...

@var상수에 대해 사용하는 것이 정확 하다고 생각 하지 않으며 @constantPHPDoc 태그 가 표시되지 않습니다 . 이를 수행하는 올바른 방법은 무엇입니까?

답변

phpDoc으로 가져 오려면 다음을 사용하십시오.

@const THING

일반적인 구조 :

@const[ant] label [description]

답변

PHP-FIG는 @var상수에 대한 사용 을 제안 합니다.

7.22. @var

@var태그를 사용하여 다음 “구조 요소”의 “유형”을 문서화 할 수 있습니다 .

  • 상수, 클래스 및 전역 범위
  • 속성
  • 전역 및 로컬 범위의 변수

통사론

@var ["Type"] [element_name] [<description>]

답변

@const정답 이 아닙니다 .

목록에있는 유일한 “공식”장소는 phpdoc.de이지만 사양은 1.0 베타로만 만들어졌고 사이트에는 이전에 사용한 적이없는 @brotherand와 같은 태그도 포함되어 @sister있으므로 해당 사이트에 대한 전반적인 신뢰도를 얻었습니다. 😉 사실상 표준은 항상 phpDoc.org였습니다.

요컨대, 비공식 표준이 언급하더라도 문서 생성자가 지원하지 않으면 사용할 가치가 없습니다.

@var 맞다 지금은 PSR (위 목록의 마지막 링크)이 초안에서 벗어 났고 phpDocumentor, Doxygen, APIGen 및 기타 사용자가 PHPDoc을 이해하는 기반이되면 다음 @type의 후속 작업이 정확합니다.@var.

답변

Netbeans를 사용합니다. 이 형식을 사용할 때 전역 및 클래스 상수에 대해 phpDoc을 구문 분석합니다.

/** @const Global constant description */
define('MY_CONST', 10);

class MyClass
{
    /** @const Class constant description */
    const MY_CONST = 10;
}

답변

유형은 항상 다음과 같기 때문에 상수 유형에 주석을 달 필요가 없습니다.

  • 스칼라 또는 배열
  • 선언시 알려진
  • 불변

@const또한 PHPDoc 표준의 일부가 아닙니다. PHP-FIG는 제안 @var하지만 이것은 PHPDoc에 의해 뒷받침되지 않으며 선언 자체에서 추론 할 수없는 정보를 추가하지 않습니다.

따라서 가독성을 위해 일반 PHPDoc docblock을 사용하여 상수를 문서화하는 것이 좋습니다.

class Foo
{
    /**
     * This is a constant.
     */
    const BAR = 'bar';
}

PHPDocs를 생성 할 때 상수를 설명하지만 주석은 깨끗하고 읽기 쉽게 유지됩니다.

답변

다음 제안 은 공식 문서 구문을 존중 합니다 .

class Foo
{
    const
        /**
         * @var string Should contain a description
         */
        MY_CONST1 = "1",
        /**
         * @var string Should contain a description
         */
        MY_CONST2 = "2";

}

답변