Tài liệu Nhận/Đăng Tham số với Doxygen hoặc PHPDoc

Question

Tôi đã xem qua tài liệu cho PHPDoc và không thể tìm thấy cách tốt để ghi lại các biến Bài đăng mà tôi đã gửi cho các phương thức khác nhau.

Vì vậy, tôi bắt đầu xem xét Doxygen với hy vọng rằng nó sẽ cung cấp cho tôi một cách tốt hơn để ghi lại tất cả các biến này. Mã của tôi liên quan đến rất nhiều yêu cầu AJAX, vì vậy hầu hết các biến được gửi qua bài đăng.

Có cách nào tốt để tôi ghi lại các biến bài đăng trong doxygen không? Tôi gặp sự cố khi xác định xem mình có gặp lỗi khi chỉ chạy với thẻ thông số chuẩn hay không.

Nếu không, có một nhà tài liệu nào khác có thể hữu ích trong quy trình này không? Hoặc tôi chỉ nên tự tay ghi lại mọi thứ và bỏ qua tìm kiếm một công cụ tài liệu tự động?

Cảm ơn!

Answer 1

Nếu các phương pháp đang đọc những người trực tiếp từ $ _POST, chứ không phải như các đối số phương pháp, sau đó tôi muốn dựa vào các @uses thẻ trong docblock của phương pháp:

/** 
* My foo() method 
* @return void 
* @uses $_POST['bar'] directly 
*/ 
public function foo() 
{ 
    echo "I use ", $_POST['bar'], "... :-)"; 
} 

Một lựa chọn khác có thể là thẻ @global :

/** 
* My bar() method 
* @return void 
* @global mixed uses the 'bar' key from the $_POST superglobal directly 
*/ 
public function foo() 
{ 
    global $_POST; 
    echo "I use ", $_POST['bar'], "... :-)"; 
} 

Tôi nhận thấy rằng từ khóa "toàn cầu" không cần thiết về mặt kỹ thuật đối với siêu siêu bên trong một phương pháp, nhưng nó giúp làm cho tài liệu được ghi lại.

---

Sửa

Lưu ý rằng theo hướng dẫn tham khảo PHPDoc của, @uses được thiết kế để hiển thị một mối quan hệ hai chiều.

phát Documentation NÊN tạo ra một @ sử dụng theo thẻ trong tài liệu của phần tử tiếp nhận liên kết trở lại các yếu tố liên quan đến thẻ @uses

Như vậy, mặc dù ngữ nghĩa @uses có thể đọc tốt hơn , @see cũng có thể được sử dụng để ghi lại tham số $ _ [POST | GET | REQUEST]. Sự khác biệt chính/duy nhất giữa hai là @see có nghĩa là liên kết một chiều tới số FQSEN được tham chiếu trong khối tài liệu