상수에 대해 PHPDocs를 올바르게 기술하는 방법은 무엇입니까?

코드는 다음과 같습니다.

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

나는 그것을 사용한다고 생각하지 않는다.@var상수에 대해 정확하고, 어떤 것도 보이지 않습니다.@constantPHPDoc 태그올바른 방법은 무엇입니까?



질문에 대한 답변



PHP-FIG는 다음을 권장합니다.@var상수의 경우.

7.22.@var

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

  • 클래스 및 글로벌 범위 모두 상수
  • 특성.
  • 변수(글로벌 범위와 로컬 범위

구문

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




@const정답이 아닙니다.

  • 레거시 php Document 또는 documents: http://manual.phpdoc.org/HTMLframesConverter/default/
  • 현재 php Document 또는 문서에는 포함되어 있지 않습니다.http://www.phpdoc.org/docs/latest/index.html
  • Wikipedia 태그 목록에 없습니다.http://en.wikipedia.org/wiki/PHPDoc#Tags
  • PHP-FIG 드래프트 PSR에는 기재되어 있지 않습니다.https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#7-tags

목록에 있는 유일한 “공식” 장소는 phpdoc.de입니다. 그러나 그곳의 사양은 1.0파운드밖에 되지 않았고, 사이트에는 다음과 같은 태그도 포함되어 있습니다.@brother그리고.@sister지금까지 사용한 적이 없기 때문에, 그 사이트의 전체적인 신뢰도는 다소 저하되고 있습니다.-) 사실상의 기준은 항상 phpDoc.org이었습니다.

즉, 일부 비공식 표준에서 언급하더라도 문서 생성기가 이를 지원하지 않으면 사용할 가치가 없습니다.

@var현재로선 올바르고 PSR(위 목록의 마지막 링크)이 드래프트에서 제외되면 phpDocumentor, Doxygen, APIGen 등이 PHPDoc을 이해하는 기반이 되며, 그 다음으로는 어떤 것이 올바른 것인지 알 수 있습니다.




이 유형은 항상 다음과 같으므로 상수 유형에 주석을 달 필요가 없습니다.

  • 스칼라 또는 배열
  • 선언 시에 알 수
  • 불변의

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

따라서 읽기 쉽도록 일반 PPDoc 문서 블록을 사용하여 상수를 문서화할 것을 권장합니다.

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

PHPDocs를 생성할 때의 상수를 나타내면서도 코멘트는 깨끗하고 읽기 쉬운 상태로 유지합니다.




나는 팥을 쓴다.다음 형식을 사용하면 phpDoc에서 글로벌 및 클래스 상수를 해석합니다.

/** @const Global constant description */ define('MY_CONST', 10);
class MyClass {
/** @const Class constant description */
const MY_CONST = 10; } 



다음 명제는 공식 문서 구문을 존중합니다.

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