PDF:

Tài liệu tham chiếu Java API
Tài liệu tham chiếu Java API được tổ chức trong trợ giúp Eclipse như
thế nào
Mariana Alupului ([email protected])
Phát triển Thông tin
Rational software, IBM
20 03 2007
Bài viết này mô tả các cách tiếp cận khác nhau để tạo ra tài liệu tham chiếu giao diện lập trình
ứng dụng Java dễ sử dụng và có thể tìm kiếm được.
Các kiến thức cơ sở
Cải thiện tính khả dụng của tài liệu sản phẩm là chìa khóa thành công của nhiều dự án. Sự
thành công này có thể được quy trực tiếp cho nỗ lực tạo ra và viết tài liệu tốt.
Bài viết này giả sử rằng bạn đã quen thuộc với phần mềm Java, cấu trúc tài liệu tham chiếu Java
API, việc sinh ra Javadoc và bây giờ bạn muốn biết thêm về việc làm thế nào để tạo ra được tài liệu
tham chiếu Java API nâng cao.
Với những người bắt đầu thì bạn phải tự làm quen với:
• Javadoc, một công cụ mã nguồn mở được Sun Microsystems tạo ra. Để biết thêm chi tiết, hãy
đọc java.sun.com/j2se/javadoc.
• JavaHelp, là một tập trợ giúp, có khả năng đánh số và tìm kiếm. Để có thêm thông tin, hãy
xem tại java.sun.com/products/javahelp.
• Các công cụ chính thức từ JavaHelp. Để có thêm thông tin, hãy tham khảo danh sách ở
java.sun.com/products/javahelp/industry.html.
• Các quy ước mã hóa Java chuẩn. Xem chi tiết tại java.sun.com/docs/codeconv và một trang
tham khảo nhanh.
• Các quy ước Javadoc. Xem chi tiết tại java.sun.com/j2se/javadoc/writingdoccomments.
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
Bài viết này mô tả các cách tiếp cận khác nhau để tạo ra tài liệu tham chiếu giao diện lập trình ứng
dụng Java dễ sử dụng và có thể tìm kiếm được. Các cách tiếp cận được mô tả ở đây là giải pháp
chuẩn Javadoc và sử dụng JavaTOC doclet tôi đã phát triển để tạo ra hệ thống trợ giúp trình bổ
© Copyright IBM Corporation 2007
Tài liệu tham chiếu Java API
Nhẫn hiệu đăng ký
Trang 1 của 14
developerWorks®
ibm.com/developerWorks/vn/
sung Eclipse. JavaTOC doclet tạo ra mục lục (TOC) cho tài liệu tham chiếu Javadoc API, mục lục
này giúp người dùng có thể dễ dàng tìm một lớp, giao diện hoặc phương thức nào đó trong tài liệu
tham chiếu API.
Tài liệu tham chiếu Javadoc API cần phải vừa duyệt được và vừa tìm kiếm được. Javadoc chuẩn
không cung cấp đầy đủ khả năng này. Một API được làm tài liệu đầy đủ có thể phục vụ cho nhiều
mục đích, nhưng lý do quan trọng nhất là cho phép người dùng hiểu một cách đầy đủ và tìm kiếm
toàn diện các chức năng API có sẵn của mình. Nếu không được làm tài liệu một cách đúng đắn
hoặc không thể tìm kiếm được thì thậm chí ngay chính tác giả cũng có thể không hiểu nổi mã
nguồn mà mình đã viết ra. Giải pháp là tập thói quen làm tài liệu cho mã nguồn và tạo cấu trúc có
thể tìm kiếm được (mục lục định hướng) cho các tham chiếu Java API. JavaTOC doclet giải quyết
vấn đề này bằng cách tạo ra cấu trúc có thể tìm kiếm được cho các tham chiếu.
Việc tìm kiếm và duyệt giả sử rằng thông tin đã được sắp xếp theo mức độ liên quan cho một truy
vấn cụ thể, tạo ra kết quả là một số lượng bất kì các trình tự đặc biệt. Ví dụ, trong Javadoc chuẩn,
một phép tìm kiếm phần mô tả của một phương thức cụ thể trong thông tin API trả lại kết quả là
phần mô tả của toàn bộ lớp.
Các cách tiếp cận được cân nhắc
Giải pháp là tập thói quen làm tài liệu cho mã nguồn. Nếu không được làm tài liệu một cách
đúng đắn thì thậm chí ngay chính tác giả cũng có thể không hiểu nổi mã nguồn mà mình đã
viết ra.
Có khá ít các công cụ để tạo ra tài liệu tham chiếu Java API. Gợi ý hiện tại của tôi là dùng kết hợp
JavaTOC doclet và Javadoc hoặc đặc tả DITA API.
• Javadoc là một công cụ do Sun sở hữu, công cụ này lấy ra các ghi chú của lập trình viên từ
mã nguồn Java và xuất chúng sang HTML. Công cụ Javadoc tạo ra cấu trúc cơ sở của tài liệu
tham chiếu Java API. Kết quả là tài liệu Javadoc HTML API cho một tập các gói và các lớp.
• JavaTOC doclet tạo ra mục lục định hướng và khả năng tìm kiếm cho tài liệu tham chiếu Java
API. Đội đặc tả IBM DITA API đã phát triển gói các kiểu chủ đề DITA để tạo ra các tệp tài liệu
Java API và bản kê định hướng cho các tham chiếu sẽ có trong hệ thống trợ giúp Eclipse.
Các ví dụ sau đây (Ví dụ tham chiếu API không có mục lục định hướng và Ví dụ tham chiếu API
có mục lục định hướng) sử dụng mã nguồn Java từ Bộ dụng cụ (Toolkit) mở DITA. Bộ dụng cụ mở
DITA phiên bản mới hơn hoặc bằng 1.0.2 đưa ra giao diện dòng lệnh như là một sự lựa chọn khác
để giúp cho những người dùng có ít kiến thức về Ant có thể sử dụng bộ công cụ được dễ dàng. Sau
khi tải xuống tệp zip, bạn có thể thấy mã nguồn được sử dụng cho ví dụ của bài viết này trong thư
mục DITA-OT1.2_src\DITA-OT1.2-src\src.
Về Javadoc và JavaTOC doclet
Sự khác biệt lớn nhất giữa trợ giúp Javadoc chuẩn và trợ giúp Eclipse Javadoc là việc cung cấp
mục lục định hướng. Trợ giúp Javadoc chuẩn cung cấp thêm một số khung để giúp bạn duyệt các
gói và các lớp. Trợ giúp Eclipse Javadoc đã được tùy biến chứa các tệp định hướng XML kiểu
Eclipse chứ không phải các khung HTML được cung cấp thêm đó. Các tệp định hướng XML kiểu
Eclipse tạo ra mục lục định hướng, mục lục này cho phép người dùng tìm một gói, lớp hoặc giao
Tài liệu tham chiếu Java API
Trang 2 của 14
ibm.com/developerWorks/vn/
developerWorks®
diện cụ thể. Giải pháp tham chiếu Eclipse Java API tùy biến cung cấp bảng kê định hướng cho các
tài liệu sẽ có trong hệ thống trợ giúp Eclipse.
Toàn bộ nền Eclipse được phát triển xoay quanh ý tưởng về các trình bổ sung. Nếu bạn muốn đưa
tài liệu trợ giúp của mình vào nền Eclipse, thì bạn phải phát triển một trình bổ sung trợ giúp mới.
Trình bổ sung đó bao gồm các tệp ảnh và tệp HTML, tệp mục lục ở dạng XML và tệp bảng kê.
JavaTOC doclet tự động sinh ra toàn bộ cấu trúc trình bổ sung Eclipse, cấu trúc này chứa tệp mục
lục định hướng XML được lấy ra trực tiếp từ mã nguồn Java.
JavaTOC doclet là chương trình được tùy biến, chương trình này cũng làm việc với công cụ
Javadoc. Doclet này tăng cường độ linh hoạt, cho phép bạn tạo ra mục lục định hướng phía trên
các tệp tài liệu Javadoc.
JavaTOC doclet được tích hợp với công cụ DITAdoclet cho đặc tả IBM DITA API, đặc tả này được
phát triển để sinh ra các tệp Java DITA (XML) API phục vụ cho việc tạo tài liệu và sinh các tham
chiếu Java API. Giải pháp này cũng bao gồm các bảng kê định hướng cho tài liệu tham chiếu Java
API, tài liệu này sẽ có trong hệ trợ giúp Eclipse.
Cấu trúc tham chiếu Eclipse Javadoc API được tạo ra với công cụ
Javadoc chuẩn
Để truy cập trợ giúp trực tuyến Javadoc chuẩn trong Eclipse, bạn có thể chọn Help > Help
Contents trên thanh thực đơn. Việc này sẽ mở trợ giúp trực tuyến trong chính trình duyệt của nó.
Trong khung ở bên trái, có khung nhìn dạng thẻ cho các liên kết mục lục, tìm kiếm và trợ giúp theo
ngữ cảnh. Ví dụ dưới đây (Hình 1) thể hiện một cấu trúc tham chiếu Javadoc API chuẩn, được sinh
ra chỉ bằng cách sử dụng công cụ Javadoc chuẩn trong môi trường Eclipse.
Hình 1. Cấu trúc các tham chiếu Javadoc API
Phần đuôi mở rộng của org.eclipse.help.toc nhận biết đây là một trình bổ sung vào hệ thống trợ
giúp.
Tài liệu tham chiếu Java API
Trang 3 của 14
developerWorks®
ibm.com/developerWorks/vn/
Ví dụ 1. plug-in.xml
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="1.0"?>
<plugin>
<extension point="org.eclipse.help.toc">
< toc file="doclet.toc.xml" primary="true"/>
</extension>
</plugin>
Ví dụ 2. MANIFEST.MF
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Doc Plug-in
Bundle-SymbolicName: org.dita.dost.doc; singleton:=true
Bundle-Version: 1.0.0
Bundle-Activator: org.dita.dost.doc.DocPlugin
Bundle-Localization: plugin
Require-Bundle: org.eclipse.ui,
org.eclipse.core.runtime
Eclipse-AutoStart: true
hoặc
Ví dụ 3. plug-in.xml
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="1.0"?>
<plugin
name = "%Plugin.name"
id = "org.dita.dost.user.doc"
version = "7.0.1.0"
provider-name = "%Plugin.providerName">
<extension point="org.eclipse.help.toc">
< toc file="doclet.toc.xml" primary="true"/>
</extension>
</plugin>
Đổi tên, id, phiên bản, và tên nhà cung cấp của trình bổ sung sang các giá trị phù hợp với dự án
của bạn.
Ví dụ 4. plugin.properties
# NLS_MESSAGEFORMAT_VAR
# ==============================================================================
# Tr# giúp tr#c tuy#n - H##ng d#n d#ch: ph#n s# đ##c d#ch
# =============================================================================
Plugin.name = Building DITA output
Plugin.providerName = IBM
Tệp doclet.toc.xml được coi là mục lục của trình bổ sung này; tệp này sẽ cung cấp dữ liệu cho thông
tin có tính phân cấp trong khung ở bên trái của cửa sổ trợ giúp Eclipse. Một tệp đơn giản có nội
dung kiểu như được hiển thị ở ví dụ 2.
Tài liệu tham chiếu Java API
Trang 4 của 14
ibm.com/developerWorks/vn/
developerWorks®
Ví dụ 5. doclet.toc.xml
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>
<toc label="Building DITA output">
<topic label="API References" href="index.html"/>
</toc>
Trong đó href = "index.html" là liên kết tới các tham chiếu javadoc api đã được tạo ra. Nếu bạn
muốn các tham chiếu đó có trong khung ở bên phải để mở các tài liệu mà không cần đến các
khung HTML thì liên kết sẽ có dạng href="overview-summary.html".
Cấu tạo thanh định hướng Javadoc chuẩn
Thanh định hướng Javadoc chuẩn không cho phép người dùng tìm kiếm một gói, lớp hay phương
thức cụ thể.
Đây là cách định hướng thẻ Javadoc được cấu tạo và mô tả bởi SUN Javadoc--Hình 2.
Hình 2. Định hướng thẻ Javadoc
Để tạo ra một tệp chú giải gói, bạn phải đặt tên cho nó là package.html và đặt tệp đó trong
thư mục gói trong cây nguồn, cùng với các tệp .java. Javadoc sẽ tự động tìm tên tệp này
trong thư mục đó. Chú ý rằng tên tệp này là giống hệt nhau đối với tất cả các gói.
Nội dung của tệp chú giả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:
Tài liệu tham chiếu Java API
Trang 5 của 14
developerWorks®
ibm.com/developerWorks/vn/
• Đừ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.
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.
Tài liệu tham chiếu Java API
Trang 6 của 14
ibm.com/developerWorks/vn/
developerWorks®
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.
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.
Tài liệu tham chiếu Java API
Trang 7 của 14
developerWorks®
ibm.com/developerWorks/vn/
Ví dụ 6. plug-in.xml
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="1.0"?>
<plugin>
<extension point="org.eclipse.help.toc">
<toc file="doclet.toc.xml" primary="true"/>
</extension>
</plugin>
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
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="1.0"?>
<plugin
name = "%Plugin.name"
id = "org.dita.dost.user.doc"
version = "7.0.1.0"
provider-name = "%Plugin.providerName">
<extension point="org.eclipse.help.toc">
<toc file="doclet.toc.xml" primary="true"/>
<toc
<toc
<toc
<toc
<toc
<toc
<toc
<toc
<toc
<toc
file="org.dita.dost.exception.toc.xml"/>
file="org.dita.dost.index.toc.xml"/>
file="org.dita.dost.invoker.toc.xml"/>
file="org.dita.dost.log.toc.xml"/>
file="org.dita.dost.module.toc.xml"/>
file="org.dita.dost.pipeline.toc.xml"/>
file="org.dita.dost.platform.toc.xml"/>
file="org.dita.dost.reader.toc.xml"/>
file="org.dita.dost.util.toc.xml"/>
file="org.dita.dost.writer.toc.xml"/>
</extension>
</plugin>
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
Tài liệu tham chiếu Java API
Trang 8 của 14
ibm.com/developerWorks/vn/
developerWorks®
Ví dụ 8. doclet.toc.xml
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>
<toc label="Building DITA output">
<topic label="Overview" href="doc\overview-summary.html">
<link toc="org.dita.dost.exception.toc.xml"/>
<link toc="org.dita.dost.index.toc.xml"/>
<link toc="org.dita.dost.invoker.toc.xml"/>
<link toc="org.dita.dost.log.toc.xml"/>
<link toc="org.dita.dost.module.toc.xml"/>
<link toc="org.dita.dost.pipeline.toc.xml"/>
<link toc="org.dita.dost.platform.toc.xml"/>
<link toc="org.dita.dost.reader.toc.xml"/>
<link toc="org.dita.dost.util.toc.xml"/>
<link toc="org.dita.dost.writer.toc.xml"/>
</topic>
</toc>
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
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>
<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">
<anchor id="org.dita.dost.index.packages"/>
<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"/>
</topic>
</toc>
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.
Tài liệu tham chiếu Java API
Trang 9 của 14
developerWorks®
ibm.com/developerWorks/vn/
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.
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ó.
Tài liệu tham chiếu Java API
Trang 10 của 14
ibm.com/developerWorks/vn/
developerWorks®
Các tải về
Mô tả
Tên
Ví dụ tham chiếu API không có mục lục định hướng
Kích thước
org.dita.dost.user.zip
381KB
Ví dụ tham chiếu API có mục lục định hướng
org.dita.dost.zip
364KB
Tài liệu tham chiếu Java API
Trang 11 của 14
developerWorks®
ibm.com/developerWorks/vn/
Tài nguyên
Học tập
• Để biết thêm chi tiết về công cụ Sun Microsystems Javadoc, hãy xem trang chủ Javadoc
• Hãy khám phá Doclet.com, một thư viện các mở rộng Doclet cho công cụ Javadoc.
• Hướng dẫn của Sun "Làm thế nào để viết các chú giải Doc cho công cụ Javadoc" mô tả các
luật và các nguyên lý của Javadoc.
• Ngôn ngữ Java có cách tiếp cận tích hợp tới tài liệu API thông qua quy ước chú giải
Javadoc. Hãy đọc bài viết của David Gallardo, "Java theory and practice: I have to document
THAT?" (Lý thuyết và thực hành Java: Tôi phải tạo tài liệu cho nó) , và học cách sử dụng thủ
thuật sinh mã của môi trường phát triển trình bổ sung để tạo các trình bổ sung Eclipse.
• Xem "Documenting your project using the Eclipse help system (Sử dụng hệ thống trợ giúp
Eclipse để tạo tài liệu cho dự án của bạn)", từ IBM developerWorks.
• Bất cứ người nào thích Eclipse cũng sẽ thấy hướng dẫn học, Eclipse Learning Guide (Hướng
dẫn học Eclipse), có rất nhiều các lời khuyên và liên kết hữu ích.
• Bài viết "Centralizing help in Eclipse" (Việc tập trung trợ giúp trong Eclipse) , minh họa cách
dùng các lợi thế của bản tính động của trợ giúp Eclipse và kiến trúc trình bổ sung để cho
phép bạn tạo ra một thư viện trợ giúp tập trung. Bài viết tập trung vào việc làm thế nào để tạo
ra một trình bổ sung Eclipse với một mục lục trợ giúp, cách sử dụng trung tâm thông tin để
mở rộng các tệp trợ giúp của bạn và làm thế nào để tạo ra một mục thực đơn mới cho phép
bạn truy cập thư viện trợ giúp tập trung từ thực đơn chính Eclipse.
• Thậm chí các lập trình viên hiếm khi cần truy cập hệ thống trợ giúp; và đôi khi bạn muốn truy
cập hệ thống trợ giúp từ xa.
Trong bài viết, "Running the WebSphere Studio help system remotely" (Chạy hệ thống trợ
giúp WebSphere Studio từ xa) , Angel Vera chỉ cho bạn cách chạy hệ thống trợ giúp lập trình
viện ứng dụng WebSphere Studio.
Lấy sản phẩm và công nghệ
• Công cụ cải tiến việc làm tài liệu cho Java của IBM alphaWorks là một công cụ giúp cải tiến
các tệp Javadoc bằng cách đưa thêm vào chúng các thông tin mới (thông tin về cú pháp, sắp
xếp và khả năng định hướng), các thông tin này được thu thập bằng cách phân tích tĩnh các
tệp lớp Java tương ứng.
• Tải về SDK trình bổ sung nền Eclipse tại trang tải về dự án eclipse.
• Gia nhập cộng đồng nền Eclipse và tải nền về tại eclipse.org. Ở eclipse.org, bạn cũng sẽ tìm
thấy một bảng chú giải các thuật ngữ và mô tả của các dự án Eclipse, cùng với các bài báo kĩ
thuật và các nhóm mới. Báo cáo nền Eclipse trình bày chi tiết các thành phần chính và các
hàm của Eclipse.
• Tìm thêm các nguồn XML trên vùng developerWorks XML .
Thảo luận
• Tìm thêm về việc kết hợp giữa các lập trình viên và những người viết tài liệu trong "API
documentation process series article" (Bài viết về các chuỗi xử lý tài liệu API) của tôi.
Tài liệu tham chiếu Java API
Trang 12 của 14
ibm.com/developerWorks/vn/
developerWorks®
• "Creating Javadoc API documentation with directly updated source" (Tạo tài liệu
Javadoc API với nguồn được cập nhật trực tiếp)
• "Creating Javadoc API documentation with indirectly updated source" (Tạo tài liệu
Javadoc API với nguồn được cập nhật gián tiếp).
• Tìm hiểu thêm về "DITA XML Specialization for Writing Language-conformant Reference
Documentation for API libraries" (Đặc tả DITA XML để viết tài liệu tham chiếu tương thích
ngôn ngữ cho các thư viện API).
Tài liệu tham chiếu Java API
Trang 13 của 14
developerWorks®
ibm.com/developerWorks/vn/
Đôi nét về tác giả
Mariana Alupului
Mariana Alupului là thư ký kĩ thuật cao cấp (chuyên viết các tài liệu liên quan tới giao
diện lập trình ứng dụng (API)) cho nhóm IBM Software, Rational Software. Ngoài việc
làm tài liệu và lãnh đạo các dự án làm tài liệu API cho Java, VB, C++ trong môi trường
lập trình phần mềm, cô còn là thành viên của đội tập đoàn IBM (IBM Corporation
team), đội này phát triển cấu trúc kiểu thông tin Darwin (Darwin Information Typing
Architecture - DITA) dựa trên XML để chuyên viết tài liệu tham chiếu thích hợp với
ngôn ngữ cho các thư viện API. Mariana trợ giúp để tạo ra các quy tắc chung về kiểu
tham chiếu API và là thành viên của liên hiệp hội đồng hỗ trợ ID và hội đồng thư ký kĩ
thuật ID. Cô là thành viên của của hội truyền thông mang tính kĩ thuật và đã có báo
cáo tại kỳ họp “Beyond the Bleeding Edge” (vượt trên các mũi nhọn công nghệ) vào
năm 2005
© Copyright IBM Corporation 2007
(www.ibm.com/legal/copytrade.shtml)
Nhẫn hiệu đăng ký
(www.ibm.com/developerworks/vn/ibm/trademarks/)
Tài liệu tham chiếu Java API
Trang 14 của 14