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

ển khai như một thư mục hoặc một tệp JAR) và tạo tệp doc.zip. 
<target name="copyPlugin" 
 description="Copy the project to workspace"> 
 <copy includeemptydirs="true" 
todir="${ECLIPSE_HOME}/workspace/${plugin.name}"> 
 === End Building ${plugin.name} Plug-in Documentation === 
 === ${now} === 
Lời bình: 
Chép dự án này vào không gian làm việc của bạn. 
Tự động xây dựng trình bổ sung 
• Làm sáng (chọn) dự án trình bổ sung của bạn. 
• Nhấn Run > External Tools > External Tools > Build Plugin 
Documentation. 
o Thực hiện việc xây dựng, cùng với các tường thuật trực tiếp và lỗi 
xuất hiện trong khung nhìn bảng điều khiển. 
o Nếu bạn nhận được lỗi 'BUILD FAILED' trong bảng điều khiển của 
mình thì hãy kiểm tra và sửa tất cả các vấn đề phát sinh và thực hiện 
lại việc xây dựng cho đến khi bạn nhận được 'BUILD 
SUCCESSFUL' ở cuối thông điệp bảng điều khiển. 
o Sau khi xây dựng thành công (trong môi trường phát triển của bạn) 
trình bổ sung tài liệu (không còn bất cứ lỗi ANT nào) thì sẽ có thư 
mục \topics cho các tệp HTML, và sẽ có tệp doc.zip trong thư mục 
gốc và tệp bảng kê trình bổ sung. 
o Các thuộc tính xây dựng sẽ chứa tất cả các tệp *.xml mục lục, 
plugin.properties, META-INF, và các tệp .project. Nếu một tệp 
doc.zip được tạo ra thì tệp build.properties cũng sẽ chứa tệp doc.zip 
đó (không được sửa). Nếu trình bổ sung được phát triển như là một 
tệp jar đơn, thì tệp build.properties cũng sẽ phải chứa các thư mục đã 
được tạo ra ở mức độ trên cùng (các chủ đề), chứ không phải là tệp 
doc.zip. 
Thư mục đích cho các tệp đầu ra (org.dita.dost.doc) 
• Trong ví dụ của chúng ta (org.dita.dost.doc plug-in), tệp xây dựng ANT 
sinh ra các tệp XML đầu ra cho trình bổ sung và một số các tệp hữu ích 
khác cho thư mục workspace\org.dita.dost.doc, hiện giờ là thư mục trình 
bổ sung của bạn. 
• Sửa giá trị của build.toc.tree từ false thành true. Tệp xây dựng ANT tạo 
đầu ra theo hai cách: 
<property name="build.toc.tree" 
value="false" /> 
<property name="build.toc.tree" 
value="true" /> 
o .project 
o plugin.xml 
o plugin.properties 
o META-
INF\MANIFEST.MF 
o topics\ — All HTML 
files. 
o doc.zip 
o primary.plugin.toc.xm
l 
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
o .project 
o plugin.xml 
o plugin.properties 
o META-
INF\MANIFEST.MF 
o topics\ — All HTML 
files. 
o doc.zip 
o org.dita.dost.doc.toc.xm
l — 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.bat — 
Tệp BAT để chạy công cụ 
, 
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.bat — 
Tệp BAT để chạy công cụ 
JavaDoc. 
JavaDoc. 
• Bạn có thể chỉnh sửa các tệp xây dựng ANT để thêm vào các mục sau: 
o Ở dự án Java plugin.properties thêm Plugin.notree = false 
Plugin.name = DITA Dost 
Plugin.providerName = I.B.M. 
Plugin.link_to = ../com.ibm.xde.mda.doc/primary.plugin.toc.xml#api 
Plugin.anchor_id = api 
Plugin.notree = false 
o 
o Ở build.xml thêm 
o 
Nạp trình bổ sung vào không gian làm việc của bạn 
Bạn có thể dùng Import Wizard (thủ thuật nạp vào) để nạp trình bổ sung tài liệu 
vào không gian làm việc của bạn. 
• Từ thanh thực đơn chính hãy chọn File > Import.... Cửa sổ thủ thuật nạp 
mở ra. 
• Chọn General > Existing Project into Workspace và nhấn Next. 
• Chọn thư mục gốc và nhấn Browse để định vị thư mục Workspace 
• Trong Projects chọn dự án org.dita.dost.doc để nạp vào. 
• Nhấn Finish để bắt đầu nạp. 
Hình 6. Nạp trình bổ sung vào không gian làm việc 1 
Hình 7. Nạp trình bổ sung vào không gian làm việc 2 
Hình 8. Nạp trình bổ sung vào không gian làm việc 3 
Về đầu trang 
Kiểm tra trình bổ sung tham chiếu Java API 
• Thiết lập môi trường thời gian chạy (runtime) đích: 
o Chọn Window > Preferences > Plug-in Development > Target 
Platform 
o Đặt Location là thư mục eclipse chính trong sản phẩm đã được cài 
đặt bên ngoài. Một danh sách các trình bổ sung trong thư mục 
Eclipse xuất hiện (bước này sẽ cần một chút thời gian). 
o Nhấn OK để lưu lại các thiết lập nền đích. 
• Từ phối cảnh phát triển trình bổ sung, tạo ra cấu hình chạy bằng cách chọn 
Run > Run. Việc này sẽ khởi chạy trang cấu hình chạy. 
o Nhấn cấu hình ứng dụng Eclipse, rồi đến nút New và đặt cho nó một 
cái tên bất kì để chỉ định nó là trình bổ sung JavaTOCdoclet Eclipse 
thử nghiệm. Chúng ta sẽ gọi nó là Test Plugin Doc. 
o Ở thẻ Main, trong trường vị trí, chọn một thư mục không gian làm 
việc. Mọi thứ mà bạn làm trong khi sử dụng thời gian chạy đích sẽ 
được ghi vào không gian làm việc đó, bao gồm cả tệp .log trong thư 
mục .metadata 
o Trong Program to Run, chọn Run a product và chọn 
org.eclipse.platform.ide 
o Ở thẻ Plug-ins, chọn Choose plug-ins and fragments to launch 
from the list 
o Trong Workspace Plug-ins, chọn các trình bổ sung mà bạn muốn 
kiểm tra. Tùy chọn này cho phép bạn kiểm tra các trình bổ sung cục 
bộ của mình, thậm chí trình bổ sung đó mới và chưa được cài đặt với 
thời gian chạy đích. 
o Để nguyên danh sách External Plug-ins như vậy. 
o Chọn hộp kiểm Add new workspace plug-ins to this launch 
configuration automatically. 
o Nhấn Apply để ghi lại các thay đổi. 
o Chuyển sang Plug-in Development perspective và nhấn Run > 
Run . 
ƒ Chọn cấu hình chạy mà bạn đã tạo ra (Test Plugin Doc) và 
nhấn Run. Thời gian chạy đích sẽ được khởi chạy. Điều này 
có nghĩa là sản phẩm mở rộng của bạn sẽ bắt đầu, nhưng sẽ 
có một bản sao của các trình bổ sung cục bộ của bạn thay vì 
phiên bản trong sản phẩm. 
ƒ GHI CHÚ: Một khi bạn đã chạy trình bổ sung của mình, cấu 
hình chạy (Test Plugin Doc) sẽ xuất hiện trong lịch sử chạy, 
vì vậy bạn có thể khởi chạy thời gian chạy đích với Run > 
Run History > Test Plugin Doc, hoặc bạn có thể sử dụng 
biểu tượng thanh công cụ. 
ƒ 
ƒ Các ngầm định sẽ khởi chạy tất cả các trình bổ sung trong nền 
đích cùng với tất cả các dự án trình bổ sung mở trong không 
gian làm việc của bạn. Việc này cùng với một số ngầm định 
khác nữa là đủ. 
Về đầu trang 
Xem tài liệu tham chiếu Java API của bạn 
Từ Eclipse Test Platform mới, chọn Help > Help Contents. Bạn sẽ thu được cửa 
sổ trợ giúp, hình 9, với trình bổ sung của mình đã được thêm vào (tương tự như 
trong hình 2). 
Hình 9. Help — Eclipse SDK 
Về đầu trang 
Đóng gói trình bổ sung 
Một khi bạn đã hoàn thành việc này thì tất cả những gì bạn còn phải làm là để 
đóng gói tất cả mọi thứ trong cấu trúc, bằng cách sử dụng Workbench User 
Guide, Export wizard. Thủ thuật này giúp bạn xuất các nguồn từ Eclipse 
workbench. 
 Về đầu trang 
Chú ý 
• 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ứ 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 
Các lời bình doc nguồn cho đặc tả 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 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. 
Tôi đã hướng dẫn các bạn cách sử dụng JavaTOC doclet để phát triển tài liệu nền 
Eclipse chứ không phải là cách tạo tài liệu cho mã nguồn. Tài liệu được tạo ra phải 
có tính chuyên nghiệp, vì vậy bạn cần rất cố gắng; để tạo tài liệu một cách đầy đủ 
cho mã nguồn của lập trình viên cho các tham chiếu Java API đã được tạo tài liệu 
đầy đủ. Giải pháp mã nguồn mở miễn phí này có thể đơn giản hóa quá trình xây 
dựng tài liệu của bạn, cho phép bạn chỉ làm việc với doclet và cấu trúc trình bổ 
sung, định hướng mục lục và các tệp HTML sẽ được tạo ra. 
Trong các bài viết tiếp theo của chuỗi bài viết developerWorks XML, tôi sẽ mô tả 
quá trình tạo tự động tài liệu Java API có thể tìm kiếm được (định hướng mục lục) 
bằng cách sử dụng công cụ DITAdoclet cho hệ thống trợ giúp trình bổ sung 
Eclipse. Bài viết Tài liệu Java API được tổ chức trong đặc tả DITA API như 
thế nào sẽ cung cấp công cụ DITAdoclet để tải về và giải thích cách dùng nó để 
tạo các tệp Java DITA API và đầu ra XHTML từ mã nguồn Java. Chúng tôi cũng 
sẽ xem xét sâu hơn công nghệ tạo tài liệu tham chiếu Java API, và một số cải tiến 
của IBM nhằm nâng cao giá trị, như là đặc tả Java DITA API và cách sử dụng nó. 
Mục lục 
• Ôn tập nhanh 
• Sử dụng JavaTOC doclet để sinh trình bổ sung Eclipse (tài liệu tham chiếu 
Javadoc API) 
• Thiết kế các ràng buộc 
• Luồng công việc 
• Tạo tài liệu Javadoc bằng cách sử dụng thủ thuật tạo Eclipse Javadoc 
(Doclet chuẩn) 
• Tạo định hướng XML mục lục và các tệp trình bổ sung Javadoc thông qua 
việc sử dụng thủ thuật sinh Eclipse Javadoc và JavaTOC doclet (Doclet tùy 
biến) 
• Sử dụng JavaAPITools (build.xml & JavaTOC doclet) và ANT để tạo trình 
bổ sung tài liệu của bạn 
• Kiểm tra trình bổ sung tham chiếu Java API 
• Xem tài liệu tham chiếu Java API của bạn 
• Đóng gói trình bổ sung 
• Chú ý 
• Kết luận