PDF:

Tài liệu tham chiếu Java API
Phần 2: Sử dụng JavaTOC doclet để sinh cấu trúc tham chiếu Eclipse
Javadoc API
Mariana Alupului ([email protected])
Phát triển Thông tin
Rational software, IBM
17 07 2009
Bài viết này (là phần 2 của loạt bài viết) 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 (API) Java dễ sử dụng và có thể tìm kiếm được.
Ôn tập nhanh
Trong phần 1 của loạt bài này, Tài liệu tham chiếu Java API được tổ chức trong trợ giúp Eclipse
như thế nào, tôi đã giới thiệu một cách tiếp cận khác để tạo ra tài liệu tham chiếu giao diện lập
trình ứng dụng (API) Java dễ sử dụng và có thể tìm kiếm được.
Bài viết này thảo luận về công cụ JavaTOC doclet, cách sử dụng và mở rộng nó. Cách tiếp cận
này sử dụng giải pháp chuẩn Javadoc và sử dụng JavaTOC doclet mà tôi đã phát triển để tạo ra hệ
trợ giúp trình bổ sung Eclipse. Công cụ JavaTOC doclet sinh ra các tệp định hướng mục lục XML
cần thiết cho hệ trợ giúp Eclipse, tài liệu tham chiếu Sun Javadoc API ở định dạng HTML. Để hiểu
được cách tiếp cận này, tôi đã đưa vào một ví dụ minh họa có sử dụng Sun Javadoc và công cụ
JavaTOC doclet (sử dụng giao diện dòng lệnh - Command Prompt).
Cấu trúc tham chiếu Eclipse Javadoc API được tạo ra với JavaTOC
doclet
Các ràng buộc thiết kế
Để trở thành một thư ký kỹ thuật (người phát triển thông tin Java API) có kỹ năng cao, bạn
phải đạt được trình độ hiểu biết thông thạo về ngôn ngữ Java, các công cụ sinh tài liệu tham
chiếu Java API và các kỹ năng.
Bạn có thể chạy JavaTOC doclet và Javadoc để sinh ra tài liệu tham chiếu Java API, định hướng
mục lục và cấu trúc trình bổ sung. Hoặc bạn có thể chỉ chạy JavaTOC doclet để tạo ra định hướng
mục lục từ các tài liệu có sẵn mà lập trình viên đã tạo ra và chuyển cho bạn.
© Copyright IBM Corporation 2009
Tài liệu tham chiếu Java API
Nhẫn hiệu đăng ký
Trang 1 của 18
developerWorks®
ibm.com/developerWorks/vn/
Luồng công việc
Với mỗi trình bổ sung mà bạn muốn đóng góp cho hệ trợ giúp Eclipse (phần tham chiếu Java API),
thì nói chung cần xử lý theo luồng sau:
• Chạy JavaTOC doclet để tạo ra tất cả các tệp trình bổ sung cần thiết cho hệ trợ giúp
Eclipse (plugin.xml, primary.plugin.toc.xml, META-INF/MANIFEST.MF, build.properties, và
plugin.properties).
Tệp plugin.xml, mở rộng điểm mở rộng org.eclipse.help.toc, cần phải chỉ ra:
1. Một tệp mục lục XML, nếu bạn chỉ có một ít các gói Java.
2. Nhiều tệp mục lục XML, khi bạn có nhiều gói Java.
• Chạy Javadoc (Sun Microsystems) trên các tệp mã nguồn Java của bạn để tạo ra các tệp
HTML cho tài liệu tham chiếu Java API.
• Kiểm tra tài liệu tham chiếu Java API đã được tạo ra.
Ant là hệ thống xây dựng Java mà ngày nay dường như tất cả mọi người đều đang sử dụng. Nếu
bạn chưa từng làm việc với Ant thì hãy xem ở trang thông tin Jakarta, hoặc "Open Source Java:
Ant" (Java mã nguồn mở: Ant).
Cách yêu thích của tôi để chạy công cụ JavaTOC doclet là thông qua hệ thống xây dựng Ant,
nhưng trong bài viết này tôi sẽ chỉ cho các bạn cách sử dụng JavaTOC doclet từ giao diện dòng
lệnh (Command Prompt).
Xây dựng các tệp đầu ra mục lục XML với dòng lệnh
Các ngôn ngữ lập trình máy tính hỗ trợ việc tạo tài liệu mã nguồn bằng cách cung cấp các
ký hiệu đặc biệt để đánh dấu bắt đầu và kết thúc của các đoạn mô tả mã nguồn. Các ký hiệu
và mô tả này được coi chung là các chú giải. Ngôn ngữ lập trình Java hỗ trợ ba loại chú giải:
nhiều dòng, dòng đơn và doc.
Bộ công cụ JavaTOC Doclet phiên bản 1.0.0 cung cấp giao diện dòng lệnh như là một sự lựa chọn
cho những người dùng ít hiểu biết về Ant để họ có thể sử dụng bộ công cụ một cách dễ dàng.
1. Hãy chắc chắn rằng Javadoc đã được cài đặt trên đường dẫn của bạn. (...\jdk1.5.0_06\bin
\javadoc.exe)
• GHI CHÚ: thông thường Javadoc sẽ có một đường dẫn có dạng C:\Program Files\Java
\jdk1.5.0_06\bin.
2. Tải về tệp JavaToc Doclet ZIP và giải nén tệp đó vào thư mục bạn chọn (ví dụ, C:\doclet\ trên
Windows). Một thư mục JavaTOC với các thư mục con bin\, demo\ và doc\ sẽ được tạo ra.
• Thư mục bin chứa các lớp Java bạn cần để chạy phần mở rộng doc như là các thư viện
jar. (DocletTOC.jar)
• Thư mục doc chứa tài liệu hướng dẫn JavaTOC và (ví dụ) tài liệu API trình bổ sung
org.dita.dost.doc ở định dạng HTML.
• Thư mục tài nguyên src chứa các tệp nguồn Java mà bạn có thể sử dụng cho ví dụ ở đây.
(bạn có thể tài về các tệp nguồn trực tiếp từ trang SOURCEFORGE: DITAOT1.3_src.zip )
3. Sử dụng tùy chọn @packages để đặt các gói có tên kiểu đủ tiêu chuẩn vào một tệp độc lập.
Tài liệu tham chiếu Java API
Trang 2 của 18
ibm.com/developerWorks/vn/
developerWorks®
4. Chạy lệnh sau từ thư mục c:\doclet> javadoc @tocdoclet @options @packages (Từ ví dụ 1
đến ví dụ 3)
Ví dụ 1. tocdoclet
-doclet com.ibm.malup.doclet.config.TOCDoclet
-docletpath C:\doclet\bin\TOCNavDoclet.jar
Ví dụ 2. các tùy chọn
-sourcepath src
-d com.ibm.doc_plugin_name
-overview src/overview-summary.html
-doctitle 'Navigation label'
-version 'plugin_version' -pluginid plugin_id
-provider 'plugin_provider_name'
-anchor 'plugin_name'
Ví dụ 3. các gói
com.ibm.package1
com.ibm.package2
...
com.ibm.packageN
Ví dụ 4. removefiles
source\..\..\package1\fileA.java,source\..\..\package2\fileB.java, , ,
source\..\..\packageN\fileN.java
5. Bằng cách dùng trình soạn thảo NotePad để mở, bạn có thể sửa các tệp này.
• JavaTOC doclet gán các giá trị tên trình bổ sung, id, phiên bản và tên nhà cung cấp cho
dự án trình bổ sung Eclipse của bạn, thể hiện trong ví dụ 2.
Điểm mở rộng từ trình bổ sung org.eclipse.help.toc nhận biết đây là một trình bổ sung
cho hệ thống trợ giúp.
Tệp doclet.toc.xml được tham chiếu đến như là mục lục cho trình bổ sung này; tệp này sẽ
cung cấp dữ liệu cho thông tin có thứ bậc ở khung bên trái của cửa sổ trợ giúp Eclipse.
• Tệp packages có nội dung giống như được thể hiện trong ví dụ 3.
6. Chạy lệnh: javadoc @tocdoclet @options @packages @removefiles — xóa tất cả các lớp
mà bạn không muốn để hiển thị ra (ví dụ 4).
Bảng các tham số đề xuất được cung cấp bởi JavaTOC doclet:
Tham số
Mô tả
-d <destination directory>
Chỉ ra thư mục đích cho tài liệu được tạo ra. Theo ngầm định, đây là thư
mục hiện tại (thư mục được chỉ định bằng đường dẫn ".").
-doclet <class>
Tạo ra đầu ra thông qua doclet thay thế.
Để chạy doclet, bạn sẽ cần phải chỉ ra lớp doclet trên dòng lệnh Javadoc,
sử dụng tùy chọn: -doclet <class>
-sourcepath <pathlist>
Chỉ ra chỗ tìm các tệp nguồn.
Theo ngầm định thì src là thư mục hiện tại.
-docletpath <path>
Chỉ ra chỗ tìm các tệp lớp doclet
Tài liệu tham chiếu Java API
Trang 3 của 18
developerWorks®
ibm.com/developerWorks/vn/
-doctitle <html-code>
Bao gồm tiêu đề cho trình bổ
sung Eclipse.
Điều này được phản ánh trong tệp manifest.mf:
Plugin.name = Building MDA RXE
-overview <file>
Chỉ ra chỗ tìm tài liệu tổng quan (tệp HTML).
—version <plug-in_version>
Chỉ ra các chi tiết id phiên bản trình bổ sung.
—provider <plugin_provider>
Chỉ ra các chi tiết tên nhà cung cấp trình bổ sung.
-anchor
Việc liên kết được chỉ ra bằng cách sử dụng tham chiếu tới mục lục đủ
tiêu chuẩn, ví dụ như là
<toc link_to="../the_other_plugin_id/path/to/toc.xml#anchor_id"/
>
-notree
Tài liệu tham chiếu Java API
Phần đóng góp org.eclipse.help.toc chỉ ra một hoặc một số các tệp XML
kết hợp, các tệp này chứa cấu trúc của trợ giúp của bạn và tích hợp của
nó với trợ giúp được đóng góp bởi các trình bổ sung khác.
Trang 4 của 18
ibm.com/developerWorks/vn/
developerWorks®
Nếu bạn định tạo tài liệu cho một dự án đầy đủ thì chỉ ra là sẽ tạo nhiều
tệp mục lục XML.
GHI CHÚ: Nếu quên tham số cờ này thì sẽ chỉ tạo ra một tệp mục lục
XML
7. Doclet tạo ra các tệp XML đầu ra cho trình bổ sung, và một số tệp hữu ích tại c:\doclet
\com.ibm.doc_plugin_name, giờ đây là thư mục trình bổ sung của bạn:
• plugin.xml
• plugin.properties
• .project
• META-INF\MANIFEST.MF
• com.ibm.packageN.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
• buildJavaDoc.xml — tệp ANT để chạy công cụ JavaDoc từ môi trường Ant.
• buildJavaDoc.bat — tệp BAT để chạy công cụ JavaDoc.
8. Chạy JavaDoc từ giao diện dòng lệnh (buildJavaDoc.bat) để tạo tệp HTML cho tài liệu API.
Sử dụng JavaTOC doclet để tạo một tệp mục lục XML
Đến giờ thì chúng ta vừa nói về doclet, hãy tiếp tục với ví dụ thực sự, sử dụng JavaTOC doclet với
các tệp nguồn DITA-OT 1.3 (DITA-OT1.3_src.zip) làm ví dụ của chúng ta.
Tệp mục lục định nghĩa các điểm mục nhập khóa thành các tệp nội dung HTML bằng cách định
nghĩa các chủ đề đã được dán nhãn được ánh xạ tới các tệp HTML, và hoạt động giống như mục
lục của một tập các nội dung HTML. Đôi khi các tệp mục lục này được đề cập đến như là các tệp
định hướng bởi vì chúng mô tả cách định hướng nội dung HTML. Một trình bổ sung có thể có một
hoặc nhiều tệp mục lục.
Chạy ví dụ org.dita.dost
Chạy tệp bat: C:\doclet\JavaTOC>TOCDoclet_dost.bat (Từ ví dụ 5 tới ví dụ 8)
Ví dụ 5. TOCDoclet_dost.bat
javadoc
@config @options @packages
Ví dụ 6. config
-doclet
com.ibm.malup.doclet.config.TOCDoclet -docletpath C:\doclet\bin\TOCNavDoclet.jar
Ví dụ 7. các tùy chọn
-sourcepath demo/src
-d demo/output/org.dita.dost.doc
-overview demo/src/overview-summary.html
-doctitle 'Building DITA output'
-pluginid org.dita.dost.docIf we
-provider XYZ
-version 1.0.1
Tài liệu tham chiếu Java API
Trang 5 của 18
developerWorks®
ibm.com/developerWorks/vn/
Ví dụ 8. các gói
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
hoặc là từ giao diện dòng lệnh, thư mụ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/overviewsummary.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
Thư mục đích cho các tệp đầu ra
• Doclet tạo ra các tệp XML đầu ra cho trình bổ sung và một số tệp hữu dụng tại C:\doclet
\JavaTOC\output\org.dita.dost.doc, giờ đây là thư mục trình bổ sung của bạn (ví dụ 9):
• plugin.xml
• plugin.properties
• .project
• META-INF\MANIFEST.MF
• org.dita.dost.doc_toc.xml— tệp XML mục lục để xây dựng cây định hướng trong trình
duyệt trợ giúp.
• buildJavaDoc.xml — tệp ANT để chạy công cụ JavaDoc từ môi trường Ant.
• buildJavaDoc.bat — tệp BAT để chạy công cụ JavaDoc.
Ví dụ 9. plug-in.xml
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.0"?>
<!-<!-<!-<!-<!-<!--
========================================================== -->
Trình bổ sung này đổnh nghĩa mổt trổ giúp trổc tuyổn
-->
đóng góp cho IBM Rational Software Modeler.
-->
Các tài liổu đổổc cổp phép - Quyổn sổ hổu cổa IBM
-->
(c) Bổn quyổn công ty IBM. Giổ bổn quyổn.
-->
========================================================== -->
<plugin
name = "%Plugin.name"
id = "org.dita.dost.doc"
version = "7.0.1.0"
provider-name = "%Plugin.providerName">
<extension point="org.eclipse.help.toc">
<toc file="org.dita.dost.doc_toc.xml" primary="true"/>
</extension>
Tài liệu tham chiếu Java API
Trang 6 của 18
ibm.com/developerWorks/vn/
developerWorks®
</plugin>
Các giá trị tên của trình bổ sung, id, phiên bản và tên nhà cung cấp được sinh ra một cách tự động
từ các thuộc tính -d, -doctitle, —version và —provider (ví dụ 10).
Ví dụ 10. plugin.properties
ổ NLS_MESSAGEFORMAT_VAR
ổ ==============================================================================
ổ Trổ giúp trổc tuyổn - Chổ dổn dổch: phổn sổ đổổc dổch
ổ =============================================================================
Plugin.name = Building DITA output
Plugin.providerName = IBM
Các tệp bảng kê trình bổ sung mở rộng các xâu ký tự của chúng bằng cách thay thế xâu với
một khóa (ví dụ %pluginName) và tạo ra một mục nhập trong tệp plugin.properties có dạng:
pluginName = "Online Help Sample Plugin" (trình bổ sung minh họa trợ giúp trực tuyến (ví dụ 11)
Ví dụ 11. META-INF\MANIFEST.MF
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Doc Plug-in
Bundle-SymbolicName: -pluginid; singleton:=true
Bundle-Version: 1.0.0
Bundle-Activator: -pluginid.DocPlugin
Bundle-Localization: plugin
Require-Bundle: org.eclipse.ui,
org.eclipse.core.runtime
Eclipse-AutoStart: true
Điểm mở rộng của trình bổ sung org.eclipse.help.toc nhận biết đây là một trình bổ sung cho hệ
trợ giúp. Tệp doclet.toc.xml được tham chiếu đến như là mục lục cho trình bổ sung này; tệp này sẽ
cung cấp dữ liệu cho thông tin có tính thứ bậc ở 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 giống như được hiển thị trong ví dụ 12.
Ví dụ 12. org.dita.dost.doc_toc.xml
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>
<toc label="Building DITA output">
<topic label="Overview" href="overview-summary.html">
<topic label="org.dita.dost.index Package" href="../index/package-summary.html">
<topic label="IndexTerm" href="../index/IndexTerm.html"/>
<topic label="IndexTermCollection" href="../index/IndexTermCollection.html"/>
<topic label="IndexTermTarget" href="../index/IndexTermTarget.html"/>
<topic label="TopicrefElement" href="../index/TopicrefElement.html"/>
</topic>
<topic label="org.dita.dost.invoker Package" href="../invoker/package-summary.html">
<topic label="AntInvoker" href="../invoker/AntInvoker.html"/>
<topic label="CommandLineInvoker" href="../invoker/CommandLineInvoker.html"/>
<topic label="JavaInvoker" href="../invoker/JavaInvoker.html"/>
</topic>
<topic label="org.dita.dost.log Package" href="../log/package-summary.html">
<topic label="DITAOTBuildLogger" href="../log/DITAOTBuildLogger.html"/>
<topic label="DITAOTEchoTask" href="../log/DITAOTEchoTask.html"/>
<topic label="DITAOTFailTask" href="../log/DITAOTFailTask.html"/>
<topic label="DITAOTFileLogger" href="../log/DITAOTFileLogger.html"/>
Tài liệu tham chiếu Java API
Trang 7 của 18
developerWorks®
ibm.com/developerWorks/vn/
<topic label="DITAOTJavaLogger" href="../log/DITAOTJavaLogger.html"/>
<topic label="LogConfigTask" href="../log/LogConfigTask.html"/>
<topic label="MessageBean" href="../log/MessageBean.html"/>
<topic label="MessageUtils" href="../log/MessageUtils.html"/>
</topic>
<topic label="org.dita.dost.module Package" href="../module/package-summary.html">
<topic label="Content" href="../module/Content.html"/>
<topic label="AbstractPipelineModule" href="../module/AbstractPipelineModule.html"/>
<topic label="ContentImpl" href="../module/ContentImpl.html"/>
<topic label="DebugAndFilterModule" href="../module/DebugAndFilterModule.html"/>
<topic label="GenMapAndTopicListModule" href="../module/MapAndTopicListModule.html"/>
<topic label="IndexTermExtractModule" href="../module/IndexTermExtractModule.html"/>
<topic label="ModuleFactory" href="../module/ModuleFactory.html"/>
<topic label="MoveIndexModule" href="../module/MoveIndexModule.html"/>
<topic label="MoveLinksModule" href="../module/MoveLinksModule.html"/>
</topic>
<topic label="org.dita.dost.pipeline Package" href="../pipeline/package-summary.html">
<topic label="AbstractPipelineInput" href="../pipeline/AbstractPipelineInput.html"/>
<topic label="AbstractPipelineOutput" href="../pipeline/AbstractPipelineOutput.html"/>
<topic label="AbstractFacade" href="../pipeline/AbstractFacade.html"/>
<topic label="PipelineFacade" href="../pipeline/PipelineFacade.html"/>
<topic label="PipelineHashIO" href="../pipeline/PipelineHashIO.html"/>
</topic>
<topic label="org.dita.dost.platform Package" href="../platform/package-summary.html">
<topic label="IAction" href="../platform/IAction.html"/>
<topic label="DescParser" href="../platform/DescParser.html"/>
<topic label="Features" href="../platform/Features.html"/>
<topic label="FileGenerator" href="../platform/FileGenerator.html"/>
<topic label="ImportAction" href="../platform/ImportAction.html"/>
<topic label="InsertAction" href="../platform/InsertAction.html"/>
<topic label="Integrator" href="../platform/Integrator.html"/>
<topic label="IntegratorTask" href="../platform/IntegratorTask.html"/>
</topic>
<topic label="org.dita.dost.reader Package" href="../reader/package-summary.html">
<topic label="AbstractReader" href="../reader/AbstractReader.html"/>
<topic label="AbstractXMLReader" href="../reader/AbstractXMLReader.html"/>
<topic label="DitamapIndexTermReader" href="../reader/DitamapIndexTermReader.html"/>
<topic label="DitaValReader" href="../reader/DitaValReader.html"/>
<topic label="GenListModuleReader" href="../reader/GenListModuleReader.html"/>
<topic label="IndexTermReader" href="../reader/IndexTermReader.html"/>
<topic label="ListReader" href="../reader/ListReader.html"/>
<topic label="MapIndexReader" href="../reader/MapIndexReader.html"/>
</topic>
<topic label="org.dita.dost.util Package" href="../util/package-summary.html">
<topic label="CatalogParser" href="../util/CatalogParser.html"/>
<topic label="CatalogUtils" href="../util/CatalogUtils.html"/>
<topic label="Constants" href="../util/Constants.html"/>
<topic label="DITAOTCopy" href="../util/DITAOTCopy.html"/>
<topic label="FileUtils" href="../util/FileUtils.html"/>
<topic label="IsAbsolute" href="../util/IsAbsolute.html"/>
<topic label="StringUtils" href="../util/StringUtils.html"/>
</topic>
<topic label="org.dita.dost.writer Package" href="../writer/package-summary.html">
<topic label="AbstractWriter" href="../writer/AbstractWriter.html"/>
<topic label="AbstractXMLWriter" href="../writer/AbstractXMLWriter.html"/>
<topic label="CHMIndexWriter" href="../writer/CHMIndexWriter.html"/>
<topic label="DitaIndexWriter" href="../writer/DitaIndexWriter.html"/>
<topic label="DitaLinksWriter" href="../writer/DitaLinksWriter.html"/>
<topic label="DitaWriter" href="../writer/DitaWriter.html"/>
<topic label="JavaHelpIndexWriter" href="../writer/JavaHelpIndexWriter.html"/>
<topic label="PropertiesWriter" href="../writer/PropertiesWriter.html"/>
</topic>
</topic>
</toc>
Tài liệu tham chiếu Java API
Trang 8 của 18
ibm.com/developerWorks/vn/
developerWorks®
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
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ố
-notree
Mô tả
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
Tài liệu tham chiếu Java API
Trang 9 của 18
developerWorks®
ibm.com/developerWorks/vn/
'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:
• plugin.xml
• plugin.properties
• META-INF\MANIFEST.MF
• 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
• buildJavaDoc.xml — tệp ANT để chạy công cụ JavaDoc từ môi trường Ant.
• 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
<?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"/>
Tài liệu tham chiếu Java API
Trang 10 của 18
ibm.com/developerWorks/vn/
developerWorks®
</extension>
</plugin>
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
<?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>
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
<?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="~/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="~/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 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
Tài liệu tham chiếu Java API
Trang 11 của 18
developerWorks®
ibm.com/developerWorks/vn/
• 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
Đó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
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
Tài liệu tham chiếu Java API
Trang 12 của 18
ibm.com/developerWorks/vn/
developerWorks®
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
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.
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.
Tài liệu tham chiếu Java API
Trang 13 của 18
developerWorks®
ibm.com/developerWorks/vn/
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ó.
Tài liệu tham chiếu Java API
Trang 14 của 18
ibm.com/developerWorks/vn/
developerWorks®
Các tải về
Mô tả
Tên
Kích thước
Java Toc file
JavaTOC.zip
108KB
Tài liệu tham chiếu Java API
Trang 15 của 18
developerWorks®
ibm.com/developerWorks/vn/
Tài nguyên
Học tập
• Tìm hiểu thêm về công cụ Sun Microsystems Javadoc.
• Xem trang chủ Javadoc để có thêm thông tin về công cụ Sun Microsystem Javadoc.
• Hãy khám phá Doclet.com một thư viện các mở rộng Doclet cho công cụ Javadoc.
• Tài liệu hướng dẫn của Sun "How to Write Doc Comments for the Javadoc
Tool" (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.
• Javadoc doclet API cho phép bạn viết các trình bổ sung Javadoc tùy biến để sinh ra các
mẫu tài liệu khác nhau, HTML, XML hoặc DITA từ các chú giải Javadoc.
• Tìm thêm các tài nguyên XML trên developerWorks XML zone. DeveloperWorks XML zone
chứa hàng trăm các bài báo, tài liệu hướng dẫn và các mẹo để giúp lập trình viên tạo ra hầu
hết các ứng dụng có liên quan đến XML, nhưng đối với những người dùng đang tìm đường đi
trong một chủ đề mới thì tất cả các thông tin này là quá nhiều.
• Documentation Enhancer for Java (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.
• 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.
• 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.
Đọ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.
• Tìm thêm các tài nguyên trên Eclipse Platform. Eclipse là một cộng đồng mã nguồn mở, các
dự án của cộng đồng này hướng đến việc cung cấp các khung làm việc ứng dụng và nền phát
triển có thể mở rộng được để xây dựng phần mềm.
• Xem thủ thuật tạo ra Javadoc cho phép bạn tạo ra Javadoc Generation. Đó là một giao
diện người dùng cho công cụ javadoc.exe có sẵn trong Java JDK.
• The Bộ công cụ DITA Open là một thực thi của đặc tả thuộc ủy ban kĩ thuật OASIS DITA cho
các lược đồ và các DTD kiến trúc kiểu thông tin Darwin. Bộ công cụ biến đổi nội dung DITA
(các ánh xạ và chủ đề) thành các định dạng có thể phát được.
• 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ìm hiểu thêm về "Java API Reference Specialization" (Đặc tả tham chiếu Java API)
cung cấp cơ sở cho việc tạo tài liệu các thư viện lớp Java.
Lấy sản phẩm và công nghệ
• Đặc tả DITA API (javaapiref0.8.zip ) có thể được sử dụng hoặc xem xét như là một ví dụ về
cách mở rộng đặc tả tham chiếu API chung.
Tài liệu tham chiếu Java API
Trang 16 của 18
ibm.com/developerWorks/vn/
developerWorks®
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.
• "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).
• Phần 1 của loạt bài này, "Tài liệu tham chiếu Javadoc API"
• "Tài liệu tham chiếu Java API được tổ chức trong trợ giúp Eclipse như thế nào"
Tài liệu tham chiếu Java API
Trang 17 của 18
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 2009
(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 18 của 18