13

nullPHPDoc で変数を記述するときに、いつ型としてを使用するかについて混乱しています。型のヒントは、外部の呼び出し元が予測して従うべき希望と期待を記述することになっているのでしょうか、それとも、実際には 1 つの非常に具体的な型になることを望んでいても、変数のすべての可能な型を文書化することになっているのでしょうか?

例 1: デフォルト値。次の関数は、null 以外の値のみを想定しています。ただし、値が渡されない場合は、デフォルトで、null何かが渡されたかどうかを判断する方法として明示的にチェックし、その場合に特別な値を返します。外部呼び出し元が整数以外を渡さないことを願っています。以下のようにタイプnullで使用する必要がありますか、それとも、何かが渡された場合に渡したいものであるため、指定する必要がありますか?@paramint

/**
 * @param int|null $bar
 */
function foo($bar = null) {
  if(is_null($bar)) { 
    return 'ABC';
  }

  return doSomething($bar);
}

例 2: インスタンス プロパティ。$bar に整数のみを含めたいとします。つまり、bar に何も設定されていない場合、このインスタンス プロパティのデフォルトの PHP 値は null です。$bar を使用するすべての場所で、以下のように null 型の可能性があることを考慮する必要がありますか?

class Foo {
  /**
   * @var int|null
   */
  public $bar;

  /**
   * @param int|null $bar
   */
  public setBar( $bar) {
    $this->bar = $bar;
  }

  /**
   * @return int|null
   */
  public function getBar() {
    return $this->bar;
  }
}

基本的に、技術的にはその値である可能性があるため、ほぼすべて@paramの@var宣言を散らかしていることに気づきます。|nullしかし、実際にはそうすべきではありません。ほとんどすべての型に の可能性が含まれていることnullを期待する必要がありますか、またはそれを想定する必要がありますnullか?

4

2 に答える 2

2

はい、PHPDoc の標準では、どこにでも null を含める必要があります (もちろん、適用される場合)。

ここを参照してください: http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.param.pkg.html

データ型は、有効な PHP 型 (int、string、bool など)、オブジェクトの型のクラス名、または単に「混合」である必要があります。さらに、パイプで区切ることにより、1 つのパラメーターに対して複数のデータ型をリストすることができます (例: "@param int|string $p1")。リストされたパラメーター、または標準の PHP 関数 func_num_args()/get_func_arg() によって解析されるオプションのパラメーターを文書化できます。func_get_arg() でリストされるパラメーターの推奨される名前の形式は次のとおりです: $paramname パラメーターが 1 つしかない場合は $paramname、... パラメーターの数が無制限の場合

于 2012-10-01T03:22:46.383 に答える