web-dev-qa-db-ja.com

定数のPHPDocを記述する正しい方法は何ですか？

私はこのコードを持っています：

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

@varを使用することが定数に対して正しいとは思わず、@constant PHPDocタグが表示されません。これを行う正しい方法は何ですか？

phpphpdoc
69
Elzo Valugi

PHP-FIGは、定数に@varを使用することを提案しています。

7.22。 @var

@varタグを使用して、次の「構造要素」の「タイプ」を文書化できます。

  • クラスとグローバルスコープの両方の定数
  • 物性
  • グローバルスコープとローカルスコープの両方の変数

構文

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

122
user2983026

@constはnot正しい答えです。

リストされている唯一の「公式」場所はphpdoc.deですが、そこにある仕様は1.0ベータ版に過ぎず、サイトには@brotherや@sisterなどのタグも含まれています。以前使用されていたため、そのサイトの全体的な信頼はやや低下しました;-)事実上の標準は常にphpDoc.orgでした。

要するに、たとえ非公式の標準がそれについて言及していても、ドキュメントジェネレータがそれをサポートしていないなら、使う価値はありません。

@varは正しい とりあえず、PSR（上記リストの最後のリンク）がドラフトを終了し、phpDocumentor、Doxygen、APIGenなどがPHPDocを理解するための基礎になると、@typeが正しくなります。 @varへ。

117
GaryJ

Netbeansを使用しています。この形式を使用すると、グローバルおよびクラス定数のphpDocを解析します。

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

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

次の 提案 を尊重 公式のドキュメント構文 ：

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

}
2
Kwadz

型は常に次のとおりなので、定数の型に注釈を付ける必要はありません。

  • スカラーまたは配列のいずれか
  • 宣言時に既知
  • 不変

@constもPHPDoc標準の一部ではありません。 PHP-FIGは@varしかし、これはPHPDocによって裏付けられておらず、宣言自体から推測できない情報は追加しません。

したがって、読みやすくするために、単純なPHPDoc docblockを使用して定数を文書化することをお勧めします。

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

PHPDocsを生成するときに定数を記述しますが、コメントは簡潔で読みやすい状態に保ちます。

0
Yogarine