Tài liệu mã Java trong một tệp tài liệu riêng biệt bằng cách nào đó được ánh xạ tới một tệp nguồn?

Điều gì sẽ là một sự thay thế tốt cho tài liệu Java nội tuyến, tức là người ta có thể có một tệp tài liệu riêng bằng cách nào đó được ánh xạ tới tệp nguồn java không?

Tôi chưa bao giờ thích phần bình luận lớn nằm rải rác trong mã.

Tôi đã và đang sử dụng tính năng Javadoc của các nhận xét gói để tránh xả mã nguồn với các nhận xét tài liệu dài dòng:

Nhận xét cấp gói

Với Javadoc 1.2, các bình luận tài liệu cấp gói có sẵn. Mỗi gói có thể có tệp nguồn nhận xét tài liệu cấp gói riêng mà công cụ Javadoc sẽ hợp nhất vào tài liệu mà nó tạo ra. Tập tin này được đặt tên package.html(và cùng tên cho tất cả các gói). Tập tin này được giữ trong thư mục nguồn cùng với tất cả các *.javatập tin. (Không đặt packages.htmltệp trong thư mục nguồn tệp tài liệu mới, vì các tệp đó chỉ được sao chép đến đích và không được xử lý.)

Tệp gói.html là một ví dụ về tệp nguồn cấp góijava.text và gói tóm tắt.html là tệp mà công cụ Javadoc tạo ra.

Công cụ Javadoc xử lý package.htmlbằng cách thực hiện ba điều ...

Sử dụng tính năng trên, tôi đã có tài liệu dài dòng chi tiết cho các lớp và phương thức trong gói được lưu trữ riêng mã, trong một tệp html chuyên dụng. Đối với các bình luận Javadoc trong các tệp java, tôi chỉ viết các giải thích ngắn gọn ở đó, thêm văn bản như

Nếu cần, tham khảo tài liệu gói để biết thêm chi tiết.

Một điều tôi đặc biệt thích về điều này là mặc dù các tài liệu nằm trong tệp riêng biệt và ở định dạng thuận tiện hơn cho các tài liệu lớn (html), nhưng nó đã được lưu trữ đủ gần với mã nguồn liên quan và tất cả các cập nhật trong đó được tự động chọn trong thời gian tòa nhà.

Bắt đầu từ Java 1.5 , bạn có thể thay thế package-info.javacùng với các lớp của gói. Tập tin này sẽ trông như thế này:

/**
 * Javadoc for your package here
 */
package com.yourpackage;

Tài liệu JLS cho thấy đây là cách ưa thích:

Lược đồ sau đây được khuyến nghị mạnh mẽ cho việc triển khai dựa trên hệ thống tệp: Khai báo gói chú thích duy nhất, nếu có, được đặt trong tệp nguồn được gọi package-info.javatrong thư mục chứa tệp nguồn cho gói ...

Chúng tôi đề nghị rằng package-info.java, nếu có, hãy thay thế package.htmljavadoc và các hệ thống tạo tài liệu tương tự khác. Nếu có tệp này, công cụ tạo tài liệu sẽ tìm kiếm nhận xét tài liệu gói ngay trước khai báo gói (có thể được chú thích) trong gói-info.java. Theo cách này, package-info.javatrở thành kho lưu trữ duy nhất cho các chú thích và tài liệu ở cấp độ gói. Nếu trong tương lai, việc thêm bất kỳ thông tin cấp gói nào khác, tập tin này sẽ chứng minh một ngôi nhà thuận tiện cho thông tin này.