4

メソッドのパラメーターである場合、配列の要素を文書化する最良の方法は何ですか? たとえば、PHPDoc ヘッダーを使用すると、次のようになります。

@param array $data

これが教えてくれないのは、どの要素が配列で必須で、何がオプションの要素かということです。これはメソッドの説明に含まれるべきだと思います。何かのようなもの：

array: $data
============ 
int     $id      Required 
name    $string  Required 
town    $string  Optional
4

3 に答える 3

4 
/**
 * @param array $data
 * 
 * @var $data[id] int, required
 * @var $data[name] string, required
 * @var $data[town] string, required
 */

doctrine と zf2 の例を使用したこの例:

/**
* @ORM\Id
* @ORM\Column(type="integer")
* @ORM\GeneratedValue
* @Form\Attributes({"type":"hidden"})
*/
protected $id;

/**
* @ORM\Column(type="string")
* @Form\Type("Zend\Form\Element\Text")
* @Form\Required({"required":"true"})
* @Form\Filter({"name":"StripTags"})
* @Form\Filter({"name":"StringTrim"})
* @Form\Validator({"name":"StringLength", "options":{"min":"5"}})
* @Form\Options({"label":"First name"})
*/
protected $firstName;
于 2013-07-22T08:59:11.007 に答える
2

正式な方法がないという質問に答えるには、最も直感的だと思われる方法を使用してみてください。私は似たようなことをします：

/**
 * @param array $data [ int $id, string $name, string $town ]
 */

ただし、この表記法はパラメーターには使用せず、戻り値として使用します。あなたの場合、メソッドの引数をオブジェクトに抽出し、代わりにそれをメソッドに渡します。

/**
 * @param User $user
 */
public function myMethod( User $user )
{ 
    //... 
}

この理由は、User オブジェクトがそのプロパティを API として他の開発者に公開し、自己文書化コードであるためです!

もう 1 つの方法は、次のように配列要素を引数に分離することです。

/**
 * @param int $id
 * @param string $name
 * @param string $town
 */
public function myMethod( $id, $name, $town )
{
    //...
}

3 つの引数はまずまずですが、私の最初の提案のように、それをリファクタリングする方法を探し始める必要があります。4 つの引数は一般的に厄介であることが認められており、リファクタリングします。

于 2013-07-22T08:50:44.587 に答える