Làm cách nào để tạo thẻ nội tuyến (yêu cầu com.sun) nhiều nền tảng hơn? Có một trình phân tích cú pháp javadoc không phải của Oracle/nhiều nền tảng không?

Question

Tôi đang viết a library chèn đã được kiểm tra đơn vị mã ví dụ (mã nguồn, đầu ra và bất kỳ tệp đầu vào nào) vào JavaDoc, với nhiều khả năng tùy chỉnh. Cách chính của việc sử dụng thư viện này là với taglets inline, such as

{@.codelet.and.out my.package.AGreatExample} 
{@.codelet my.package.AGreatExample} 
{@.file.textlet examples\doc-files\an_input_file.txt} 
{@.codelet.and.out my.package.AGreatExample%eliminateCommentBlocksAndPackageDecl()} 

Kể từ khi tùy chỉnh taglets (và thậm chí doclets) yêu cầu com.sun, điều này có nghĩa là họ gần như không đa nền tảng như Java chính nó. (Không chắc chắn nếu điều này có liên quan, nhưng từ "javadoc" - và thậm chí chuỗi con "doc" - không nằm trong số Java 8 Language Specifications.)

Tôi không thích ý tưởng viết một thư viện bị hạn chế cách này. Vậy tôi phải làm gì? Suy nghĩ của tôi cho đến thời điểm này là

• Để tận dụng lợi thế của trình phân tích cú pháp javadoc hiện tại, tôi gắn thẻ com.sun. Tuy nhiên, tôi thực hiện sự phụ thuộc này vào com.sun là "mỏng" như có thể. Tức là, tôi đặt ít mã trong lớp thẻ càng tốt, để lại phần lớn mã ở nơi khác, nơi không phụ thuộc vào com.sun.
• Tôi làm việc hướng tới việc tạo trình phân tích cú pháp của riêng mình, chỉ chỉ tìm kiếm các thẻ tag cụ thể của tôi. Đây là một nỗi đau, nhưng không quá khủng khiếp. Bạn lặp qua các dòng của mỗi tệp nguồn Java, tìm kiếm \{@\.myTagletName (.*?)\}. Khi bạn nắm bắt được văn bản đó, nó khá giống với mã trong thẻ tag com.sun.
• Trình phân tích cú pháp này sẽ phải chạy trước khi thực thi javadoc và do đó sẽ yêu cầu cấu trúc thư mục trùng lặp. (1) mã ban đầu của bạn, với các thẻ tùy chỉnh chưa được phân tích, (2) bản sao của mã đó, với đầu ra được phân tích cú pháp. Tôi muốn sao chép tất cả tất cả mã vào thư mục trùng lặp và sau đó phân tích cú pháp chỉ những tệp Java được biết có các thẻ này (các lớp được "đăng ký" theo cách nào đó với trình phân tích cú pháp).

Đây có phải là phương pháp hợp lý không? Có một trình phân tích cú pháp javadoc/taglet đa nền tảng khác đã tồn tại ở đó chưa, vì vậy tôi không phải cuộn của riêng mình? Có bất kỳ nội dung nào có nền tảng chéo là như đã tồn tại ở đó không? Là JavaDoc chính nó không phải là nền tảng chéo hay chỉ là các thẻ và tài liệu tùy chỉnh?

Tôi muốn có một viễn cảnh thô bạo về việc có bao nhiêu người bị khóa khỏi thư viện của tôi vì quyết định này (để sử dụng thẻ nội tuyến), nhưng chủ yếu là tôi đang tìm kiếm giải pháp lâu dài.

(Mặc dù liên kết của tôi Java 8 ở trên, tôi đang sử dụng Java 7.)

---

tín dụng để @fge cho đề nghị taglet, nhiều thanh lịch hơn original idea của tôi, và để @ Michael cho đáng ngại nhưng hữu ích com.sun cảnh báo.

Answer 1

Lúc đầu, lưu ý rằng có sự khác biệt giữa các phụ thuộc sun.* và com.sun.*. Không gian tên sun.* chứa các lớp thực thi Máy ảo Java của Oracle. Bạn should not use such dependencies vì API nội bộ của JVM của Oracle có thể thay đổi trong các bản phát hành trong tương lai và bởi vì không gian tên này có thể không được cung cấp bởi các triển khai JVM không phải Oracle khác.(Trên thực tế, thậm chí Android's JVMships with one của sử dụng rộng rãi hơn sun.* lớp học.)

Sau đó là com.sun.* namespace được sử dụng bởi Sun Microsystems để thực hiện các ứng dụng Java của nó. Một ví dụ về sử dụng hợp pháp các phụ thuộc com.sun.* là khuôn khổ Jersey của Sun là originally deployed trong không gian tên com.sun.jersey.*. (Vì mục đích hoàn chỉnh, lưu ý rằng các phiên bản Jersey gần đây are deployed trong không gian tên org.glassfish.jersey.* bắt đầu bằng phiên bản 2.0 không tương thích với API Jersey 1.) Để tham khảo thêm, lưu ý cách Oracle thậm chí không đề cập đến không gian tên com.sun.*when discussing được áp đặt bằng cách sử dụng không gian tên sun.*. Ngoài ra, hãy xem this related question trên Stack Overflow.

Do đó, việc sử dụng phụ thuộc com.sun.* là một thỏa thuận khác so với phụ thuộc sun.*. Bằng cách sử dụng các lớp học com.sun.*, bạn nên khóa chính mình vào API của một thư viện cụ thể, chứ không phải với một JVM cụ thể. Ví dụ: bạn có thể tránh sử dụng trực tiếp không gian tên com.sun.jersey.* bằng cách sử dụng không gian tên JAX-RS được chuẩn hóa chuẩn hóa. Theo nghĩa này, phụ thuộc com.sun.* là sản phẩm cụ thể và độc quyền và không được nhầm lẫn với các API chuẩn hóa của Java thường được tìm thấy trong không gian tên javax.*.

Nếu tôi là bạn, tôi sẽ gắn bó với các thẻ đó là triển khai hoàn thiện và được công nhận. Oracle là khá xác định not to break APIs (nếu không, họ có lẽ cũng sẽ di chuyển các thẻ để com.oracle.*) và tôi thấy không có lý do tại sao họ đột nhiên sẽ thay đổi cấu trúc gói taglet. Và nếu họ muốn, bạn chỉ cần cập nhật công nghệ của bạn. Nếu ứng dụng của bạn vi phạm bản phát hành Java mới, người dùng của bạn sẽ tìm kiếm bản cập nhật phần mềm của bạn. Bởi vì bạn không chạy dự án taglet, tôi đồng ý với bạn rằng việc tách logic của bạn khỏi một API nước ngoài nói chung là một ý tưởng tốt vì nó là cho bất kỳ sự phụ thuộc nào. Ngoài ra, việc sử dụng các thẻ cho trường hợp sử dụng của bạn khá nhiều nhận ra các nguyên tắc KISS và DRY.