Tài liệu tham chiếu Java API

iải gói là một chú giải tài liệu lớn, được viết dưới dạng 
HTML, giống như tất cả các chú giải khác nhưng có một ngoại lệ: 
Chú giải tài liệu không được chứa các ngăn cách chú giải /** và */ hoặc các dấu 
hoa thị ở đầu. Khi viết chú giải, bạn nên tóm tắt về gói ở câu đầu tiên và không đặt 
tiêu đề hoặc bất cứ văn bản nào ở giữa và câu đầu tiên. 
Bạn có thể đưa vào đó các thẻ gói; giống như mọi chú giải tài liệu, tất cả các thẻ 
ngoại trừ {@link} phải xuất hiện sau phần miêu tả. Nếu bạn thêm một thẻ @see 
vào một tệp chú giải gói thì thẻ đó phải có tên với đầy đủ các điều kiện. 
SUN Javadoc sẽ sinh ra đầu ra bắt nguồn từ bốn kiểu khác nhau các tệp "nguồn": 
Các tệp nguồn ngôn ngữ Java (.java), các tệp chú giải gói, các tệp chú giải tổng 
quan và các tệp chưa xử lý hỗn hợp.
Tổng quan 
Trang tổng quan là trang đầu của tài liệu API này, trang này cung cấp một 
danh sách tất cả các gói cùng với bản tóm tắt cho mỗi gói. Trang này cũng 
có thể chứa mô tả toàn diện của tập các gói. LỜI BÌNH: 
• Đừng quên viết Javadoc cấp độ gói trong một tệp có tên là 
Overview.html. Nên đặt tệp này ở thư mục gốc, nơi có các tệp mã. 
Javadoc có khả năng lấy tệp đó và sử dụng nội dung của nó. 
. 
Gói (package) 
Mỗi gói có một trang, trang này chứa danh sách các lớp và các giao diện 
của nó cùng với bản tóm tắt cho mỗi thành phần. Trang này có thể chứa 
năm loại: giao diện, lớp, ngoại lệ, lỗi, và hằng số. 
LỜI BÌNH: 
• Đừng quên viết Javadoc cấp độ gói trong tệp có tên là package.html. 
Nên đặt tệp này vào thư mục, nơi mà có các tệp mã cho gói đó. 
Javadoc có khả năng lấy tệp đó và sử dụng nội dung của nó. 
. 
Lớp/Giao diện (Class/Interface) 
Mỗi lớp, giao diện, lớp bên trong, giao diện bên trong có một trang riêng 
của nó. Mỗi trang này có 3 phần bao gồm một mô tả lớp/giao diện, các 
bảng tóm tắt và các mô tả thành viên chi tiết: 
Mỗi mục tóm tắt chứa câu đầu tiên của phần mô tả chi tiết cho phần đó. 
Các mục tóm tắt được sắp xếp theo bảng chữ cái, trong khi các mô tả chi 
tiết thì theo thứ tự chúng xuất hiện trong mã nguồn. Việc này bảo tồn việc 
phân nhóm mang tính lôgic đã được lập trình viên lập ra. 
Sử dụng (Use) 
Mỗi gói, lớp và giao diện đã được làm tài liệu có trang sử dụng riêng của 
mình. Trang này miêu tả các gói, lớp, phương thức, hàm thành viên của lớp, 
trường nào sử dụng bất cứ phần nào của lớp hoặc gói đã cho. 
Cây - Phân bậc theo lớp (Tree) 
Có một trang cây (phân bậc theo lớp) cho tất cả các gói, cùng với một phân 
bậc cho mỗi gói. Mỗi trang phân bậc chứa một danh sách các lớp và một 
danh sách các giao diện. 
Nên tránh (Deprecated) 
Trang API nên tránh liệt kê toàn bộ các API được khuyên là nên tránh. 
Người ta khuyên không nên dùng các API nên tránh, thường là do các quá 
trình cải tiến tạo ra, và họ cũng thường cung cấp các API thay thế. Các API 
nên tránh có thể bị xóa trong các lần thực thi trong tương lai. 
Chỉ mục (Index ) 
Chỉ mục chứa một danh sách theo thứ tự bảng chữ cái của tất cả các lớp, 
các giao diện, các hàm thành viên của lớp, các phương thức và các trường. 
Trước/Kế tiếp (Prev/Next) 
Các liên kết này đưa bạn tới lớp, giao diện, gói hoặc trang có liên quan ở 
trước hay tiếp sau. 
Khung/ Không khung (Frames/No Frames) 
Các liên kết này sẽ cho hiện hoặc ẩn các khung HTML. Tất cả các trang sẽ 
có hoặc không có khung. 
Về đầu trang 
Sử dụng JavaTOC doclet để sinh ra cấu trúc tham chiếu Eclipse Javadoc API 
Cách tiếp cận thông tin có cấu trúc như trong XML sử dụng Eclipse JavaTOC 
doclet và kiểu trợ giúp Javadoc thỏa mãn các yêu cầu của tài liệu tham chiếu Java 
API có thể duyệt và tìm kiếm được. 
Để kích hoạt định hướng trong một trình bổ sung trợ giúp Eclipse, người phát triển 
thông tin phải cung cấp mục lục (TOC) được viết như một tài liệu XML. Tài liệu 
này được cung cấp với một chỉ mục có thể xếp gọn lại được ở bên trái và tài liệu 
HTML ở bên phải. Có thể sử dụng Javadoc hoặc đặc tả IBM DITA Java API để 
tạo ra các tệp HTML. 
Bằng cách sử dụng JavaTOC doclet, bạn có thể tạo ra mục lục bằng tay hoặc tự 
động. JavaTOC doclet sinh ra cho bạn cấu trúc mục lục các tham chiếu Java API, 
cấu trúc này liệt kê các gói và các lớp, các giao diện chứa trong đó. 
Để tạo ra các tệp HTML tham chiếu API, bạn có thể chạy công cụ Javadoc hoặc 
sử dụng giải pháp đặc tả IBM DITA API để ủy quyền và sinh ra các tệp HTML 
tham chiếu Java API -- Hình 3. 
Hình 3. Bộ soạn thảo HTML—Kit 
Nếu bạn sử dụng JavaTOC doclet, tài liệu tham chiếu API vừa có thể duyệt được 
và vừa có thể tìm kiếm được. Khả năng có thể tìm kiếm được là do cách tiếp cận 
thông tin có cấu trúc (XML) đã được sử dụng. 
Một trong những hiệu ứng phụ có lợi của việc sử dụng XML để sinh ra cấu trúc 
của tài liệu tham chiếu API là nội dung sẽ được đánh chỉ mục một cách tự động, 
phục vụ cho việc tìm kiếm; nếu bạn dùng giải pháp Javadoc chuẩn để sinh ra nội 
dung, thì ngầm định là nó sẽ không được đánh số để phục vụ cho việc tìm kiếm. 
Về đầu trang 
Các tệp cần thiết cho cấu trúc tham chiếu Eclipse Java API và việc sinh mục lục 
Các liệt kê dưới đây cho ta các ví dụ về các tệp XML mục lục được sử dụng để 
sinh cấu trúc mục lục định hướng tham chiếu Java API ở trên. Bằng cách sử dụng 
JavaTOC doclet, các tệp có thể được sinh ra bằng tay hoặc tự động. Xem phần tải 
xuống dưới đây để tải về các ví dụ mục lục XML tham chiếu Java API cho Eclipse. 
Liệt kê dưới đây đưa ra ví dụ của một trình bổ sung tham chiếu Eclipse Java API, 
trình bổ sung này tham chiếu tới một tệp XML mục lục. 
Ví dụ 6. plug-in.xml 
Liệt kê dưới đây đưa ra cùng ví dụ về một trình bổ sung tham chiếu Eclipse Java 
API, trình bổ sung này tham chiếu đến hơn một tệp XML mục lục dựa vào cấu 
trúc gói Java. Khi quan sát tài liệu, sẽ không có sự khác biệt nào giữa việc sử dụng 
cách tiếp cận một tệp XML mục lục hay nhiều tệp XML mục lục. 
Ví dụ 7. plug-in.xml 
 <plugin 
 name = "%Plugin.name" 
 id = "org.dita.dost.user.doc" 
 version = "7.0.1.0" 
 provider-name = "%Plugin.providerName"> 
Bạn có thể sử dụng các phần tử navref và anchor, thêm thuộc tính anchorref của 
phần tử ánh xạ, để tạo ra các điểm tích hợp trong đầu ra Eclipse, nơi mà tệp định 
hướng được lấy vào hoặc tự gắn vào tại thời gian chạy. Để có thêm thông tin về 
việc ủy quyền các tệp định hướng Eclipse, hãy xem các tài nguyên Eclipse 
 Ví dụ 8. doclet.toc.xml 
 <topic label="Overview" href="doc\overview-
summary.html"> 
Mục lục XML chính phải có tiêu đề (nhãn trong Eclipse), để nạp vào mục lục của 
trợ giúp đó. 
Tệp org.dita.dost.index.toc.xml cũng chỉ là một mục lục và phải có định dạng 
giống hệt như bất cứ tệp toc.xml nào khác. 
Ví dụ 9. org.dita.dost.index.toc.xml 
<toc label="org.dita.dost.index Package" 
link_to="../doclet.toc.xml#java.packages"> 
 <topic label="org.dita.dost.index Package" 
 href="doc/org/dita/dost/index/package-overview.html"> 
 <topic label="IndexTerm" 
href="doc/org/dita/dost/index/IndexTerm.html"/> 
 topic label="IndexTermCollection" 
href="doc/org/dita/dost/index/IndexTermCollection.html"/>
 <topic label="IndexTermTarget" 
href="doc/org/dita/dost/index/IndexTermTarget.html"/> 
 <topic label="TopicrefElement" 
href="doc/org/dita/dost/index/TopicrefElement.html"/> 
Sau khi soạn thảo hoặc thêm tài liệu API mới vào tệp mã nguồn, bạn nên tạo ra tài 
liệu để chắc chắn rằng sẽ thu được kết quả như mong đợi. 
Trong Eclipse 3.2, toàn bộ trình bổ sung doc có thể được chuyển thành một tệp jar 
đơn, tệp này bao gồm tất cả các tệp sẽ có trong tệp doc.zip và các tệp trình bổ sung 
thông thường: manifest.mf, plug-in.xml, plug-in.properties,... Trước Eclipse 3.2, 
các tệp Javadoc được sinh ra sẽ ở trong tệp doc.zip cùng với các tệp HTML tĩnh và 
các tệp HTML lược đồ điểm mở rộng. 
Mã nguồn không được tạo tài liệu sẽ khó hoặc không thể hiểu, không thể sử dụng 
được, và không thể quản lý được. JavaToc doclet là một công cụ đáng giá. Tôi 
thực sự hy vọng rằng bài viết này sẽ giúp bạn tìm thấy một số điểm thú vị trong 
việc kết hợp JavaToc doclet vào dự án của mình. 
Về đầu trang 
Ghi chú 
"Sự đơn giản là linh hồn của hiệu quả". — Austin Freeman 
"Ngày nay chúng ta sống trong thời đại của chuyên môn hóa. Lượng thông tin có 
trong môi trường kiến thức lớn tới mức để hiểu và làm việc với nó, mỗi người phải 
trở thành một chuyên gia. Vì ngày càng có nhiều các kiến thức quan trọng, nên 
việc học tập cũng cần đa dạng hơn và chúng ta cũng cần có nhiều chuyên gia 
hơn." 
Thông tin được cung cấp trong tài liệu này chưa từng được thực hiện bất cứ kiểm 
tra IBM chính thức nào và được cung cấp "như hiện có", không có bảo đảm ở bất 
kì dạng nào, cả rõ ràng và hàm ý. 
Việc sử dụng thông tin ở đây hoặc việc thực thi bất cứ kĩ thuật nào được mô tả 
trong tài liệu này là trách nhiệm của người đọc và phụ thuộc vào khả năng của 
người đọc để đánh giá và tích hợp chúng vào môi trường hoạt động của mình. 
Về đầu trang 
Kết luận 
Một bài viết trong tương lai, Cấu trúc tham chiếu Eclipse Java API được sinh 
ra với JavaTOC doclet sẽ mô tả quy trình sử dụng JavaTOC doclet và hệ thống 
trợ giúp trình bổ sung Eclipse để tạo ra một cách tự động tài liệu tham chiếu Java 
API có thể tìm kiếm được (mục lục định hướng). Trong các bài viết sắp tới của 
loạt bài này, chúng tôi cũng sẽ khai thác sâu hơn về việc ủy quyền và công nghệ 
sinh tài liệu API cũng như một số cải tiến của IBM nhằm nâng cao giá trị, bao 
gồm đặc tả Java DITA API và cách sử dụng nó. 
Mục lục 
• Cấu trúc tài liệu tham chiếu Java API 
• Xây dựng tài liệu tham chiếu Java API dễ sử dụng và có thể tìm kiếm được 
• Các cách tiếp cận được cân nhắc 
• Về Javadoc và JavaTOC doclet 
• Cấu trúc tham chiếu Eclipse Javadoc API được tạo ra với công cụ Javadoc 
chuẩn 
• Cấu tạo thanh định hướng Javadoc chuẩn 
• Sử dụng JavaTOC doclet để sinh ra cấu trúc tham chiếu Eclipse Javadoc 
API 
• Các tệp cần thiết cho cấu trúc tham chiếu Eclipse Java API và việc sinh 
mục lục 
• Ghi chú 
• Kết luận