Có cách nào để phpDoc ghi lại một mảng các đối tượng dưới dạng tham số không?

Question

Trong PHPDoc tạo tài liệu tôi có thể gây PHPDoc để tạo ra một liên kết đến một định nghĩa kiểu tùy chỉnh cho một param được sử dụng

@param CustomType $variablename 

và hoạt động tuyệt vời. Tuy nhiên, mã tôi hiện đang tạo tài liệu yêu cầu thông số CustomType [], tức là một mảng của CustomType được cho biết. Tôi muốn tài liệu hướng dẫn rõ ràng rằng một mảng là bắt buộc, nhưng khi tôi sử dụng

@param CustomType[] $variablename 

phpDoc không còn nhận ra loại và do đó không thể liên kết đến định nghĩa của nó. Điều này khá quan trọng trong trường hợp này - Tôi đang ghi lại một API có một số loại khá phức tạp cần được cung cấp.

Tôi đã thử một số cú pháp khác nhau cho điều này và tất cả đều coi các mục nhập là các loại biến riêng biệt hoặc nhận dạng kiểu phá vỡ trong tài liệu.

Chặn điều này tôi sẽ chỉ ghi chú trong ghi chú tham số, nhưng có vẻ rõ ràng hơn để hiển thị mảng-tham số của tham số trong loại.

EDIT

Với phpDocumentor 2 (trong đó sáp nhập với DocBlox) các

@param CustomType[] $paramName 

công trình cú pháp, và như đã nêu trong câu trả lời @ PhpStorm Styx của hỗ trợ gõ-gợi ý với cú pháp đó.

Câu trả lời được chấp nhận được cập nhật một cách thích hợp.

Answer 1

Phiên bản mới của hỗ trợ tài liệu PHP /** @var sometype[] */ cú pháp. Thậm chí phức tạp hơn: /** @var (sometype|othertype)[] */. http://www.phpdoc.org/docs/latest/guides/types.html#arrays PHPStorm cũng hỗ trợ cú pháp này.

Answer 2

Điều tốt nhất bạn có thể làm là:

@param array $variablename an array of {@link CustomType} objects 

Điều này sẽ giúp người đọc nhận ra kiểu dữ liệu thực sự của $ variablename, trong khi cho thấy sự kỳ vọng của những gì các mảng chứa.

Điều này sẽ không đủ để giúp tự động hoàn thành của IDE khi nói đến việc sử dụng thành viên từ $ variablename và các thuộc tính/phương thức mong đợi của CustomType xuất hiện. Có thực sự không có cách nào để có được hành vi đó hiện nay.

Answer 3

Xem các ví dụ sau từ: https://code.google.com/p/google-api-php-client/source/checkout nơi được mô tả cấu trúc mảng của tham số đầu vào.

/** 
    * Set the OAuth 2.0 access token using the string that resulted from calling authenticate() 
    * or Google_Client#getAccessToken(). 
    * @param string $accessToken JSON encoded string containing in the following format: 
    * {"access_token":"TOKEN", "refresh_token":"TOKEN", "token_type":"Bearer", 
    * "expires_in":3600, "id_token":"TOKEN", "created":1320790426} 
    */ 


/** 
    * Insert a new file. (files.insert) 
    * 
    * @param Google_DriveFile $postBody 
    * @param array $optParams Optional parameters. 
    * 
    * @opt_param bool convert Whether to convert this file to the corresponding Google Docs format. 
    * @opt_param string targetLanguage Target language to translate the file to. If no sourceLanguage is provided, the API will attempt to detect the language. 
    * @opt_param string sourceLanguage The language of the original file to be translated. 
    * @opt_param string ocrLanguage If ocr is true, hints at the language to use. Valid values are ISO 639-1 codes. 
    * @opt_param bool pinned Whether to pin the head revision of the uploaded file. 
    * @opt_param bool ocr Whether to attempt OCR on .jpg, .png, or .gif uploads. 
    * @opt_param string timedTextTrackName The timed text track name. 
    * @opt_param string timedTextLanguage The language of the timed text. 
    * @return Google_DriveFile 
    */ 

Answer 4

Các tài liệu PHPDoc ghi nhận tại http://www.phpdoc.org/docs/latest/guides/types.html

mảng

Một bộ sưu tập của các biến không rõ loại. Có thể chỉ định các loại thành viên mảng, xem chương về mảng để biết thêm thông tin.

Và ... không có liên kết và không có chương "trên mảng". Vì vậy, không, điều này trông giống như một tính năng sắp tới.