Tài liệu tham chiếu Java API (Phần 2)

href="../pipeline/AbstractPipelineInput.html"/> 
 <topic label="AbstractPipelineOutput" 
href="../pipeline/AbstractPipelineOutput.html"/> 
 <topic label="org.dita.dost.platform Package" href="../platform/package-
summary.html"> 
 <topic label="org.dita.dost.reader Package" href="../reader/package-
summary.html"> 
 <topic label="AbstractXMLReader" 
href="../reader/AbstractXMLReader.html"/> 
 <topic label="DitamapIndexTermReader" 
href="../reader/DitamapIndexTermReader.html"/> 
 <topic label="GenListModuleReader" 
href="../reader/GenListModuleReader.html"/> 
 <topic label="org.dita.dost.writer Package" href="../writer/package-
summary.html"> 
 <topic label="JavaHelpIndexWriter" 
href="../writer/JavaHelpIndexWriter.html"/> 
Bây giờ thì chúng ta đã có tất cả các tệp trình bổ sung, các tệp này đã được đưa 
vào cho hệ trợ giúp Eclipse. Bạn có cấu trúc của tài liệu tham chiếu Java API, tài 
liệu này giúp định hướng trong trình bổ sung trợ giúp Eclipse thông qua mục lục 
(TOC) được viết như là một tài liệu XML. Nhu cầu duyệt được và tìm kiếm được 
được thỏa mãn với cách tiếp cận thông tin có cấu trúc này, sử dụng XML. 
Tài liệu được cung cấp với một danh mục có thể rút gọn lại được ở bên trái và tài 
liệu HTML ở bên phải 
Chạy JavaDoc để tạo tệp HTML 
Chạy JavaDoc từ giao diện dòng lệnh từ thư mục 
C:\doclet\JavaTOC\demo\output\org.dita.dost.doc (buildJavaDoc.bat) để tạo ra các 
tệp HTML cho tài liệu tham chiếu API. 
C:\doclet\JavaTOC\demo\output\org.dita.dost.doc>javadoc -sourcepath src -d 
doc -doctitle "Building DITA output" -overview src\overview.html 
org.dita.dost.index org.dita.dost.invoker org.dita.dost.log org.dita.dost.module 
org.dita.dost.pipeline org.dita.dost.platform org.dita.dost.reader org.dita.dost.util 
org.dita.dost.writer org.dita.dost.exception 
Về đầu trang 
Sử dụng JavaTOC doclet để tạo ra nhiều tệp mục lục XML 
Một tệp Java API đơn điển hình có thể chứa từ bảy tệp gói trở lên. Với JavaTOC 
doclet, bạn chỉ duy trì một tệp (package.txt), và phần còn lại sẽ được tạo ra. Bạn 
có thể giảm đáng kể thời gian phát triển và có thể tập trung vào việc làm tài liệu 
API bởi vì JavaTOC tạo ra 100% mã trợ giúp trình bổ sung cho bạn. 
Chạy cùng ví dụ org.dita.dost 
Chạy JavaTOC doclet giao diện dòng lệnh từ C:\doclet\ directory. 
C:\doclet\JavaTOC>javadoc @tocdoclet options.org.dita.dost @packages (Ví dụ 
13) 
Ví dụ 13. options.org.dita.dost 
-sourcepath demo/src 
-d demo/output2/org.dita.dost.doc 
-overview src/overview-summary.html 
-provider XYZ -doctitle 'Building DITA output' 
-notree 
trong đó tôi giới thiệu tham số -notree: 
Tham số Mô tả 
-notree 
Chỉ ra là tạo nhiều tệp mục lục XML 
GHI CHÚ: Nếu thiếu tham số này thì sẽ chỉ 
tạo ra một tệp mục lục XML. 
hoặc 
C:\doclet\JavaTOC>javadoc -doclet com.ibm.malup.doclet.config.TOCDoclet -
docletpath C:\doclet\JavaTOC\bin\TOCNavDoclet.jar -sourcepath demo/src -d 
demo/output/org.dita.dost.doc -doctitle 'Building DITA output' -pluginid 
org.dita.dost.doc -provider XYZ -version 1.0.1 -overview demo/src/overview-
summary.html -notree org.dita.dost.index org.dita.dost.invoker org.dita.dost.log 
org.dita.dost.module org.dita.dost.pipeline org.dita.dost.platform 
org.dita.dost.reader org.dita.dost.util org.dita.dost.writer 
Thư mục đích cho các tệp đầu ra (org.dita.dost.doc) 
• Doclet tạo ra các tệp XML đầu ra cho trình bổ sung và một số các tệp hữu 
ích tại C:\doclet\JavaTOC\demo\output\org.dita.dost.doc. Đây là thư 
mục trình bổ sung mới của bạn: 
o plugin.xml 
o plugin.properties 
o META-INF\MANIFEST.MF 
o doclet.toc.xml 
org.dita.dost.index.toc.xml, 
org.dita.dost.invoker.toc.xml, 
org.dita.dost.log.toc.xml, 
org.dita.dost.module.toc.xml, 
org.dita.dost.pipeline.toc.xml, 
org.dita.dost.platform.toc.xml, 
org.dita.dost.reader.toc.xml, 
org.dita.dost.util.toc.xml, 
org.dita.dost.writer.toc.xml — các tệp XML mục lục để xây dựng 
cây định hướng trong trình duyệt trợ giúp 
o buildJavaDoc.xml — tệp ANT để chạy công cụ JavaDoc từ môi 
trường Ant. 
o buildJavaDoc.bat — tệp BAT để chạy công cụ JavaDoc. 
Tệp org.dita.dost.index.toc.xml chỉ là một mục lục khác, và cần có định dạng 
giống hệt như bất cứ tệp toc.xml nào khác (ví dụ 14). 
Ví dụ 14. plug-in.xml 
 <plugin 
 name = "%Plugin.name" 
 id = "org.dita.dost.user.doc" 
 version = "7.0.1.0" 
 provider-name = "%Plugin.providerName"> 
trong đó "doclet.toc.xml" là tệp chính. Điều quan trọng ở đây là định nghĩa mục 
lục này là mục lục chính (ví dụ 15). 
Ví dụ 15. doclet.toc.xml 
Khi xem tài liệu thì sẽ không có sự khác biệt nào giữa việc sử dụng phương pháp 
này và việc chỉ đơn giản đưa thêm vào các phần tử chủ đề một cách trực tiếp (ví 
dụ 16). 
Ví dụ 16. 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="~/index/package-
overview.html"> 
 topic label="IndexTermCollection" 
href="~/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 sửa 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 
để khẳng định chắc chắn và kiểm tra rằng kết quả thu được là những gì bạn đã 
mong đợi. 
Bây giờ lấy trình bổ sung của bạn và thả nó vào thư mục các trình bổ sung của nền, 
khởi chạy Eclipse và chọn Help -> Help Contents. 
Chạy JavaDoc để tạo ra tệp HTML 
Để tạo ra tài liệu tham chiếu Java API (định dạng HTML) cho ví dụ của chúng ta 
(org.dita.dost): 
• Chạy tiện ích javadoc trên mã Java bằng cách thực hiện lệnh đó, hoặc 
• Chạy tệp bat buildJavaDoc.bat (ví dụ 17). 
Ví dụ 17. buildJavaDoc.bat 
javadoc 
-sourcepath src -d doc -doctitle "DITA XML" -overview src\overview.html 
org.dita.dost.index org.dita.dost.invoker org.dita.dost.log 
org.dita.dost.module org.dita.dost.pipeline org.dita.dost.platform 
org.dita.dost.reader org.dita.dost.util org.dita.dost.writer 
org.dita.dost.exception 
Về đầu trang 
Đóng gói trình bổ sung 
Mỗi phần tử chủ đề được biểu diễn trong tài liệu cuối cùng bằng một mục trong 
danh sách định hướng. Các chủ đề này có thể được lồng vào nhau (chúng có thể 
chứa nhiều chủ đề hơn) và mỗi chủ đề trỏ đến một tệp HTML. Một khi bạn đã làm 
việc này thì tất cả những gì bạn cần phải làm là đóng gói mọi thứ theo cấu trúc 
được thể hiện ở hình 1 (chú ý rằng tên thư mục trình bổ sung tương ứng với các 
thuộc tính id và phiên bản của trình bổ sung đã được định nghĩa trong plugin.xml). 
Hình 1. Thư mục trình bổ sung 
Để tiện lợi và giảm kích thước tệp, Eclipse cho phép bạn giữ tất cả các tài liệu 
thực sự của mình (các tệp HTML) trong một tệp ZIP được gọi là doc.zip, do vậy 
bạn có thể sử dụng cấu trúc thư mục được hiển thị trong hình 2. 
 Hình 2. Cấu trúc thư mục của doc.zip 
Về đầu trang 
Xem tài liệu của bạn 
Cách dễ nhất để kiểm tra trình bổ sung của bạn là đơn giản chỉ việc thả toàn bộ thư 
mục (như trên) vào thư mục các trình bổ sung của một nền Eclipse đã được cài đặt, 
và sau đó khởi chạy Eclipse và chọn Help > Help Contents. Bạn sẽ thu được một 
cửa sổ trợ giúp với trình bổ sung của bạn đã được thêm vào (giống như trong hình 
3). 
 Hình 3. Help — Eclipse SDK 
Về đầu trang 
Ghi chú 
"Sự đơn giản là linh hồn của tính hiệu quả". — Austin Freeman 
Thói quen viết lời bình tốt rất quan trọng đối với chất lượng của đoạn mã được 
viết ra, cũng như là chất lượng của sản phẩm cuối cùng sẽ sử dụng đoạn mã đó. 
Thông tin được cung cấp trong tài liệu này là các quan sát và kĩ thuật của tôi, với 
danh nghĩa là một thư ký kỹ thuật, nó chưa từng được thực hiện bất cứ sự kiểm tra 
chính thức của IBM 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 ý. 
Công cụ JavaTOC doclet là một phát kiến mở của tác giả Mariana Alupului. Phát 
kiến này là một phần của các tài sản trí tuệ của IBM và được công bố tại 
www.ip.com. 
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 
Nguồn tham chiếu Java API được sở hữu bởi các lập trình viên và chúng được 
chỉnh sửa bởi cả các lập trình viên và các thư ký kĩ thuật. 
JavaTOC Doclet được trình bày trong tài liệu này có thể được sử dụng để tạo tài 
liệu trợ giúp tham chiếu Java API dựa trên HTML và một lượng nhỏ các thành 
phần tài liệu bổ sung. Thông qua việc sử dụng doclet này có thể dễ dàng tạo ra tài 
liệu nền Eclipse, tài liệu này sau đó có thể được sử dụng để tạo ra định dạng đầu ra 
XML và HTML cho các hệ thống trợ giúp Eclipse có sẵn. Chúng ta đã xem cách 
sử dụng JavaTOC doclet để xây dựng tài liệu nền Eclipse. Giải pháp mã nguồn mở 
này có thể đơn giản hóa việc xây dựng tài liệu của bạn, cho phép bạn làm chỉ làm 
việc với doclet, trình bổ sung và tài liệu tham chiếu sẽ được tạo ra cho bạn. Theo 
thời gian sẽ có ngày càng nhiều các bổ sung. 
Trong các bài viết tiếp theo của loạt bài về lĩnh vực developerWorks XML, Tài 
liệu Java API được tổ chức trong đặc tả DITA API như thế nào, Tôi sẽ mô tả 
quá trình sử dụng công cụ DITAdoclet cho hệ trợ giúp trình bổ sung Eclipse để 
sinh tự động tài liệu Java API có thể tìm kiếm được (định hướng mục lục). Chúng 
tôi cũng sẽ xem xét sâu hơn công nghệ Java API, và 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 
• Ôn tập nhanh 
• Cấu trúc tham chiếu Eclipse Javadoc API được tạo ra với JavaTOC doclet 
• Sử dụng JavaTOC doclet để tạo một tệp mục lục XML 
• Sử dụng JavaTOC doclet để tạo ra nhiều tệp mục lục XML 
• Đóng gói trình bổ sung 
• Xem tài liệu của bạn 
• Ghi chú 
• Kết luận