Làm cách nào để PHPDoc gọi lại?

Question

Tôi có một phương pháp trích xuất cây chuyển đổi cây preorder đã sửa đổi từ cơ sở dữ liệu và các bộ lọc sử dụng chức năng gọi lại. Ví dụ:

/** 
* 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; 
} 

Tôi không chắc chắn những gì PHPDoc nên cho biến $filter - đó là một cuộc gọi lại, đó là những gì tôi đã chỉ ra, nhưng tôi không chắc chắn nếu đó là chính xác.

Ngoài ra, bất kỳ ý kiến ​​khác về chất lượng (hoặc thiếu) trong mã này sẽ được đánh giá :)

Answer 1

Gợi ý loại chính xác là callable, đã có sẵn trong ví dụ: PhpStorm trong một thời gian dài và là một phần của PSR-5 hiện đang được đặc điểm kỹ thuật.

(Tôi ngạc nhiên không ai khác đề cập callable, nó không có gì mới và đã được sử dụng ở khắp mọi nơi trong nhiều năm - để hiểu biết của tôi, callback không và không bao giờ là một PHP định nghĩa pseudo-type)

Lưu ý rằng callable bao gồm không chỉ đóng cửa, nhưng cũng gọi lại "old school" PHP, ví dụ array($object, 'methodName') hoặc array('ClassName', 'methodName') và thậm chí 'function_name' - để tối đa hóa tính hữu dụng của API, bạn nên bao gồm tất cả các trường hợp sử dụng đó, điều này khá dễ dàng, vì cả hai call_user_func và call_user_func_array hỗ trợ tất cả bốn loại cuộc gọi: function-name as string, object/tên phương thức, lớp/tên phương thức và đóng.

Answer 2

Các tài liệu cho tag @param dường như không đã được cập nhật trong kiếp, vì vậy nó doesn' t nói bất cứ điều gì về đóng cửa hoặc thậm chí gọi lại được thực hiện với create_function().

Nếu phpDocumentor từ chối nhận dạng callback làm loại dữ liệu, bạn sẽ phải đi với mixed.

Answer 3

phpDoc không thực sự xác định loại biến được chấp nhận là gì, chỉ cần chúng phải là tên của các loại biến hợp lệ php. Trong trường hợp này "gọi lại" sẽ là chính xác. Đó là tên của loại giả trong PHP.

Answer 4

"gọi lại" không hoạt động như một kiểu dữ liệu hợp lệ trong phpDocumentor ... Tôi vừa xác minh nó ... bằng cách sử dụng PHP 5.2.4, ít nhất. Có khả năng là "các kiểu dữ liệu hợp lệ" phụ thuộc vào phiên bản PHP bạn chạy phpDocumentor với.