PHPDoc per array di argomenti a lunghezza variabile

Question

Esiste una sintassi per documentare le funzioni che richiedono un singolo array di configurazione, piuttosto che singoli parametri?

sto pensando specificamente di librerie in stile CodeIgniter, che utilizzano un meccanismo simile a questo:

<?php 

// 
// Library definition 
// 

class MyLibrary { 
    var $foo; 
    var $bar; 
    var $baz; 
    // ... and many more vars... 


    /* Following is how CodeIgniter documents their built-in libraries, 
    * which is mostly useless. AFAIK they should be specifying a name 
    * and description for their @param (which they don't) and omitting 
    * @return for constructors 
    */ 

    /** 
    * @access public 
    * @param array 
    * @return void 
    */ 
    function MyLibrary($config = array()) { 
    foreach ($config as $key => $value) { 
     $this->$key = $value; 
    } 
    } 
} 

// 
// Library usage: 
// 

// Iniitialize our configuration parameters 
$config['foo'] = 'test'; 
$config['bar'] = 4; 
$config['baz'] = array('x', 'y', 'z'); 

$x = new MyLibrary($config); 

?> 

Quindi la mia domanda è: esiste un modo supprted di documentare l'array di configurazione oltre la semplice puramente testuale descrizione? Specificare realmente un valore corretto @param [type] [name] [desc] che consente a PHPDoc di analizzare valori utili?

Per inciso, CodeIgniter in realtà sovrascrive solo i propri valori con quelli passati attraverso l'array $ config come sopra, consentendo effettivamente di clobber membri privati. Non sono un fan, ma sono bloccato con esso.

Answer 1

non ho mai visto alcun modo "buono" di documentare questo - e non ho mai visto niente che potrebbe essere utilizzato da IDE (come Eclipse PDT) per i parametri che alludono sia :-(

avrei detto "fare come il vostro quadro fa", ma come hai detto tu, che cosa fa, qui, non è abbastanza buono ...

Forse un elenco/quick sort di chiavi possibili potrebbe essere meglio di niente, però, un po 'come questo:

@param array $config [key1=>int, otherKey=>string] 

Non so come sarebbe interpretato da phpDocumentor o un IDE ... Ma potrebbe valere la pena di provare?

Questo è, btw, uno dei motivi per cui tendo ad evitare quel tipo di modo di passare i parametri - almeno quando non ci sono troppi parametri (opzionali) per un metodo.

Answer 2

Una descrizione di testo, a qualsiasi grado di completezza che si desidera, è davvero l'unica opzione. Puoi renderlo leggibile come vuoi, ma gli strumenti di analisi del codice (phpDocumentor, supporto IDE) non hanno modo di sapere come il tuo $array è effettivamente strutturato in fase di runtime.

Sono d'accordo con i molti commentatori che scrivendo codice in questo modo scambiano la convenienza della codifica per la leggibilità del codice.

Answer 3

la correttezza matrice @param notazione per array è precisata PHPlint

Si può usare per documentare una matrice di configurazione in modo utile:

Esempio:

/** 
* Does stuff 
* 
* @param array[int|string]array[string]Object $config 
* 
* @return array[int]string 
*/ 
public function foo(array $config) 
{ 
    // do stuff here 

    return array('foo', 'bar', 'baz'); 
} 

Answer 4

È possibile effettuare ciò:

 
/** 
* @param array $param1 
* @param string $param1['hello'] 
*/ 
function hey($param1) 
{ 
} 

e netbeans lo raccoglieranno ma phpdoc rovinerà la documentazione

Answer 5

Io uso sempre i tag <pre> in situazioni come questa. Ex.:

/** 
* @param array $ops An array of options with the following keys:<pre> 
*  foo: (string) Some description... 
*  bar: (array) An array of bar data, with the following keys: 
*   boo: (string) ... 
*   far: (int) ... 
*  baz: (bool) ... 
* </pre> 
*/ 

La maggior parte dei IDE e generatori di documentazione che ho usato sembrano per rendere questo in un modo ragionevole, anche se naturalmente non forniscono alcun tipo di controllo o di verifica dei parametri array.

Answer 6

Attualmente non esiste un metodo "ufficiale" (come in "supportato da più strumenti") per eseguire questa operazione.

Il PHP figura sta discutendo è al momento in https://groups.google.com/d/topic/php-fig/o4ko1XsGtAw/discussion

Answer 7

ho usato le classi.

<?php 
class MyLibrary { 
    var $foo; 
    var $bar; 
    var $baz; 

    /** 
    * @param MyLibraryConfig|null $config 
    */ 
    function MyLibrary($config = null) { 
     if (isset($config->foo)) { 
      $this->foo = $config->foo; 
     } 
     if (isset($config->baz)) { 
      $this->baz = $config->baz; 
     } 
     if (isset($config->bar)) { 
      $this->bar = $config->bar; 
     } 
    } 
} 

/** 
* @property string $foo 
* @property int $bar 
* @property array $baz 
*/ 
class MyLibraryConfig { 
} 

Funziona abbastanza bene, il problema principale è che il codice diventa pieno di classi specifiche. Possono essere annidati in modo da poter riutilizzare parti della configurazione.