Come dovrei PHPDoc richiamare?

Question

Ho un metodo che estrae un albero trasversale albero preordine modificato dal database, e filtri che utilizzano una funzione di callback. Per esempio:

/** 
* Recursive function for building the Cas_Template_TreeNode. 
* 
* @static 
* @param array $rows 
* @param callback $filter A function to filter the tree by (return a value convertible to false to remove the item from the tree) 
* @return array 
*/ 
private static function MakeTreeGivenDbRows($rows, $filter = null) 
{ 
    if ($filter === null) 
    { 
     $filter = function($unused) 
     { 
      return true; 
     }; 
    } 
    $result = array(); 
    $childrenCount = 0; 
    for ($idx = 0; $idx < count($rows); $idx += $childrenCount + 1) 
    { 
     $current = $rows[$idx]; 
     $childrenCount = self::ChildrenCountFromRow($current); 
     if (!$filter($current)) 
     { 
      continue; 
     } 
     $childrenStartAt = $idx + 1; 
     $childRows = array_slice($rows, $childrenStartAt, $childrenCount); 
     $children = self::MakeTreeGivenDbRows($childRows, $filter); 
     $result[] = new Cas_Template_TreeNode(self::MakeNodeGivenDbRow($current), $children); 
    } 
    if (empty($result)) 
    { 
     return null; 
    } 
    return $result; 
} 

Non sono sicuro di quello che il PHPDoc dovrebbe essere per la variabile $filter - è un callback, che è quello che ho indicato, ma non sono sicuro se questo è corretto.

Inoltre, ulteriori osservazioni sulla qualità (o la sua assenza) in questo codice sarebbe apprezzato :)

Answer 1

la correttezza del tipo di suggerimento è callable, che è stato disponibile in es PhpStorm per lungo tempo, ed è parte di PSR-5, attualmente in fase specifica.

(Mi sorprende che nessuno altro ha menzionato callable, non è niente di nuovo ed è stato utilizzato in tutto il mondo per anni - a mia conoscenza, callback non è mai stato un PHP definito pseudo-type)

Nota che callable include non solo chiusure, ma anche callback PHP "vecchia scuola", es array($object, 'methodName') e e anche 'function_name' - per massimizzare l'utilità della tua API, dovresti coprire tutti questi casi d'uso, il che è abbastanza semplice, dal momento che sia call_user_func che call_user_func_array supportano tutte e quattro le varietà di callables: nome-funzione come stringa, oggetto/nome-metodo, classe/nome-metodo e chiusura.

Answer 2

La documentazione per il tag @param non sembra sono stati aggiornati in eoni, quindi doesn' Non dire nulla sulle chiusure o sui callback effettuati con create_function().

Se phpDocumentor rifiuta di riconoscere callback come tipo di dati, dovrete andare con mixed.

Answer 3

PHPDoc realtà non specifica quali sono i tipi di variabili accettate sono, solo che dovrebbero essere i nomi dei tipi di variabili php validi. In questo caso "callback" sarebbe corretto. Questo è il nome dello pseudo-tipo in PHP.

Answer 4

"callback" funziona come un tipo di dati valido phpDocumentor ... Ho appena verificato che ... utilizzando PHP 5.2.4, almeno. È possibile che "i tipi di dati validi" dipendano dalla versione di PHP con cui esegui phpDocumentor.