web-dev-qa-db-ja.com

PHPDoc：可変数の引数を持つ関数の文書化

可変数の引数を受け入れるクラスメソッドを文書化するための推奨される方法は何ですか？

多分このようなもの？

<?php

class Foo {
    /**
     * Calculates the sum of all the arguments.
     *
     * @param mixed [$arg1, $arg2, ...]
     *
     * @return float the calculated sum
     */
    public static function sum() {
        return array_sum(func_get_args());
    }
}

注：原則として、この種のことは可能な限り避けるべきだと思います。そうは言っても、それが避けられない残りのいくつかのケースをまだ文書化するのは素晴らしいことです。

phpphpdoc
26
Wilco

可変数の引数を使用し、_PHP >= 5.6_も使用している場合は、すでに説明したPHPDoc _,..._構文に準拠した可変個引数関数（可変数の引数を許可）を使用でき、PHPStormはドキュメントも適切に。可変個引数関数を使用すると、引数を配列に取り込むためにfunc_get_args()が不要になります。

_/**
 * @param mixed $args,... Explainatorium!
 */
function variadiculous(...$args) {
    // NOTE: $args === func_get_args()
    foreach ( $args as $arg ) {
        /* do work */
    }
}
_

PHPStormは、ドキュメントを_@param array $args_として自動生成します。これは、技術的には、関数内でvariadiculousis_array($args)がtrueであるためです。上記のように_@param mixed $args,..._を読み取るように変更し、ホットキーを使用してコード内の別の場所から関数シグネチャを表示すると、PHPStormはvariadiculous($args : ...array|mixed)を表示します-PHP> = 5.6

17
OnethingSimple
/**
 * @param mixed $numbers,... Description
 */
Public function sum ($numbers)

このメソッドでは、$ numbersは使用されません。

10
Rygu

...構文 の場合、PHPStorm2017.1は以下を使用します。

/**
 * @param Type[] ...$values One or more values.
 */
public function func(Type ...$values) {
    // ...
}
5
Marty

注目に値するのは、次のようなドキュメントブロックがあることです。

/**
 * @param Type[] ...$values One or more values.
 */
public function func(Type ...$values) {
    // ...
}

... Typeの配列を渡すことができるように見えるかもしれません。

Foo()->func([Type, Type, Type])

...これは明らかに今、致命的なエラーをスローします。

どこ：

Foo()->func(...[Type, Type, Type])

...メソッド呼び出しで構造化を解除したので、そうではありません。

とにかくここでのポイントは、PHPStormがドキュメントブロックをどのように処理するかを実験していて、ドキュメントブロックで$args変数を方向付ける方法に応じて、...$argsまたは$args,...のいずれかでIDEに返されるヒントのタイプを決定することです。 。

オプションの長さの関数/メソッドパラメータがあり、それらが渡される特定の順序がある場合に、下の例示された画像のメソッドに名前で渡す必要がある値を提案する方法が本当に必要です。

「デフォルトの引数、$arg1 = 'default', $arg2 = trueを設定するだけ」と思うかもしれませんが、これは通常は理にかなっていますが、場合によっては

疑似例：

/**
 * @param int ...$args Hour, Minute, Second, Timezone, $arg [, ...$args]
 */
public static function createA(int ...$args) {}

/**
 * @param int $args,... Hour, Minute, Second, Timezone, $arg [, ...$args]
 */
public static function createB(int ...$args) {}

/**
 * @param int[]|int $args,... Hour, Minute, Second, Timezone, $arg [, ...$args]
 */

public static function createC(int ...$args) {}

enter image description here

...つまり、次のいずれかです。

...正解です（オリエンテーションを念頭に置いてください：...$argsまたは$args,...）

1
userabuser