Tại sao jQuery không sử dụng JSDoc?

Question

Hay là họ và nó không có trong nguồn? Tôi thực sự muốn có được một cái gì đó mà sẽ ngừng js-doc-toolkit từ freaking ra mỗi khi nó phân tích cú pháp jQuery. Nó cũng có nghĩa là tôi không thể viết tài liệu một cách chính xác bất kỳ mã nào bằng cách sử dụng jQuery như là một sự phụ thuộc mà không cần ít nhất là đặt một số khối js-doc soạn sẵn, mà không tài liệu đúng đắn cấu trúc của jQuery. Có một giải pháp chung mà tôi không biết? Tôi đã thử googling, btw.

Answer 1

Tôi sẽ chụp ảnh trong bóng tối ở đây vì tôi không thể nói cho nhóm jQuery về lý do tại sao Tôi sẽ không sử dụng JSDoc. JSDoc, ít nhất là lần cuối tôi kiểm tra, không có cách nào sạch để hỗ trợ quá tải phương thức (hoặc chuyển dịch tham số ... bất cứ tên nào bạn muốn cho nó ở đây) và jQuery sử dụng nó khắp nơi. Chúng ta hãy xem ví dụ phổ biến đơn giản với .animate():

.animate({ height: 5 }) 
.animate({ height: 5 }, 100) 
.animate({ height: 5 }, 100, "linear") 
.animate({ height: 5 }, 100, "linear", func) 
.animate({ height: 5 }, 100, func) 
.animate({ height: 5 }, func) 
.animate({ height: 5 }, { duration: 100, queue: false }) 
.animate({ height: 5 }, { duration: 100, easing: "linear" }) 
.animate({ height: 5 }, { duration: 100, easing: "linear", complete: func }) 

Tất cả trong số này là hợp lệ, vì parameter types are checked and shifted as needed để hỗ trợ như bất kỳ tình huống quá tải càng tốt ... Đây chỉ là lẫn lộn địa ngục ra khỏi JSDoc, không có cách nào sạch để thêm các tham số tùy chọn này cho tài liệu. Xin vui lòng sửa tôi nếu điều này đã thay đổi, nhưng cuối cùng tôi nhìn (và có lẽ là lần cuối cùng đội đã xem xét) đây vẫn là trường hợp.

Một xem xét tiềm năng khác là cách một số phương thức được tạo khi jQuery chạy, ví dụ (một trong nhiều), hầu như tất cả event handler shortcuts là generated in a loop hành vi tương tự cho các phương pháp khác ... JSDoc thế hệ thực sự không hoạt động tốt ở đây.

Answer 2

Không biết tại sao họ không thêm các bình luận JSDoc nhưng những kẻ Google Closure dường như giữ một phiên bản cập nhật của "externs" cần thiết cho trình biên dịch đóng cửa với tối ưu hóa tiên tiến

http://code.google.com/p/closure-compiler/source/browse/trunk/contrib/externs/jquery-1.6.js?r=1152

Answer 3

Trong khi tôi không thể thêm bất cứ điều gì khác mà những người khác không liên quan đến câu hỏi ban đầu, tôi có thể cung cấp một liên kết đến một cái gì đó có thể tự động tài liệu jQuery.

Nó thực hiện điều này bằng cách thực hiện nó trong môi trường thời gian chạy, và sau đó phân tích cú pháp cây kết quả. Giống như JSDoc, nó sử dụng Rhino đã được sửa đổi. Đó là trong giai đoạn trứng nước nhưng tôi hy vọng điều này có ích cho một người nào đó. :)

https://bitbucket.org/nexj/njsdoc