PHPDoc: Dokumentieren einer Funktion mit einer variablen Anzahl von Argumenten

Lesezeit: 3 Minuten

Was ist die empfohlene Methode zum Dokumentieren einer Klassenmethode, die eine variable Anzahl von Argumenten akzeptiert?

Vielleicht so etwas?

<?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());
    }
}

Hinweis: Als allgemeine Regel stelle ich mir vor, dass solche Dinge nach Möglichkeit vermieden werden sollten. Davon abgesehen wäre es schön, die verbleibenden wenigen Fälle, in denen es nicht vermieden werden kann, noch zu dokumentieren.

Wenn Sie eine variable Anzahl von Argumenten verwenden und auch verwenden PHP >= 5.6 dann können Sie variadische Funktionen verwenden (die eine variable Anzahl von Argumenten zulassen), die immer noch dem PHPDoc entsprechen ,... Syntax bereits erwähnt und PHPStorm wird die Dokumentation auch richtig interpretieren. Die Verwendung variadischer Funktionen eliminiert die Notwendigkeit func_get_args() um Argumente in einem Array zu erfassen.

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

PHPStorm generiert die Dokumente automatisch als @param array $args denn technisch gesehen, wenn innerhalb der Funktion variadiculous is_array($args) ist wahr. Ich ändere es in Lesen @param mixed $args,... wie oben und wenn ich den Hotkey verwende, um eine Funktionssignatur von woanders in meinem Code anzuzeigen, wird PHPStorm angezeigt variadiculous($args : ...array|mixed) — Ich empfehle die Verwendung dieser Methode, wenn Sie PHP >= 5.6 verwenden

Im Falle der ... SyntaxPHPStorm 2017.1 verwendet:

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

  • Dies scheint eine problematische Beschreibung zu sein, da sie impliziert, dass Sie ein Array als Parameter übergeben sollten, das nicht wahr ist.

    – Mark Kaplun

    30. Dezember 2017 um 8:34 Uhr

  • Auf einen Blick, bis Sie das bemerken ... unmittelbar im Anschluss.

    – Martin

    30. Dezember 2017 um 8:42 Uhr

  • Nun, ich habe es nicht bemerkt 😉 eine seltsame Notation

    – Mark Kaplun

    30. Dezember 2017 um 8:46 Uhr

  • Dies wurde in 2018.1.7 behoben (lt youtrack.jetbrains.com/issue/WI-29429). Jetzt sollte der DocBlock mit der Methodensignatur übereinstimmen: @param Type ...$values One or more values.

    – Thiago Barcelona

    4. Mai 2020 um 12:07 Uhr


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

In der Methode werden keine $Zahlen verwendet.

  • Details zu dieser “,…”-Syntax finden Sie unter manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/…

    – ashnazg

    25. Januar 2013 um 16:01 Uhr

  • Phpstorm versteht diese Syntax nicht und warnt vor der Anzahl der Argumente

    – Hübscher Nerd

    30. September 2015 um 13:00 Uhr

  • @PHPst tut es – zumindest v10. Aber Sie müssen 2 Parameter verwenden: ($number,...$numbers);

    – Sebas

    13. Februar 2016 um 6:00 Uhr


Etwas Erwähnenswertes ist, dass mit einem Doc-Block wie:

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

… es scheint, als könnten Sie eine Reihe von passieren Typez.B

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

… dies wirft offensichtlich jetzt einen schwerwiegenden Fehler aus.

Wo:

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

… nicht so, wie Sie es beim Methodenaufruf destrukturiert haben.

Wie auch immer, der Punkt hier ist, dass ich damit experimentiert habe, wie PHPStorm den Doc-Block behandeln würde und je nachdem, wie Sie sich orientieren $args Variable in Ihrem Dokumentblock, mit entweder ...$args oder $args,... bestimmt die Art der Hinweise, die Sie in Ihrer IDE zurückerhalten.

Ich hätte wirklich gerne eine Möglichkeit, die Werte vorzuschlagen, die Sie namentlich an die Methode im Beispielbild unten übergeben sollten, falls Sie eine optionale Länge von Funktions-/Methodenparametern haben, mit einer bestimmten Reihenfolge, in der sie übergeben werden sollten.

Sie könnten denken: “Legen Sie einfach Standardargumente fest, $arg1 = 'default', $arg2 = true” was normalerweise Sinn macht, aber in Fällen

Pseudo-Beispiel:

/**
 * @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) {}

Geben Sie hier die Bildbeschreibung ein

…also entweder:

  • https://stackoverflow.com/a/38275992/1290575
  • https://stackoverflow.com/a/43622600/1290575

…ist die richtige Antwort (nur zur Orientierung: ...$args oder $args,...)

1186880cookie-checkPHPDoc: Dokumentieren einer Funktion mit einer variablen Anzahl von Argumenten

This website is using cookies to improve the user-friendliness. You agree by using the website further.

Privacy policy