PDF:

Tài li u tham chi u Java API
Page 1 of 21
Tài li u tham chi u Java API
!
)
M c
" #$
%
!&
'(
*'
: Trung bình
Mariana Alupului, Phát tri n Thông tin, Rational software, IBM
10 07 2009
Bài vi t này bàn thêm v JavaTOC doclet, cách s d ng và m r ng nó. Các cách ti p c n
c
mô t là gi i pháp chu n Javadoc và s d ng công c
t o ra h tr giúp trình b sung Eclipse.
Tôi s ch y JavaTOC doclet trong Eclipse thông qua th thu t Custom doclet, và th hai thông
qua h th ng xây d ng Ant. Công c JavaTOC t o ra nh h ng XML m c l c cho tài li u
tham chi u Java API.
Ô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 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. Các cách ti p c n
c mô t trong bài vi t là gi i pháp chu n
Javadoc và s d ng JavaTOC doclet tôi ã phát tri n t o ra h tr giúp trình b sung Eclipse.
Trong ph n 2 c a lo t bài này, S d ng JavaTOC doclet
t o c u trúc tham chi u Eclipse Javadoc API
bài vi t trình bày v JavaTOC doclet (bao g m c vi c t i d li u v ) và cách dùng Command Prompt (giao
di n dòng l nh) s d ng JavaTOC doclet. Bài vi t mô t cách JavaTOC doclet t o ra nh h ng m c l c
XML và kh n ng tìm ki m nâng cao cho tài li u tham chi u Javadoc API.
S d ng JavaTOC doclet
sinh
trình b sung Eclipse (tài li u
tham chi u Javadoc API)
H#c cách yêu c u l p trình viên tr giúp
mà không quan tâm n vi c các k$
n ng k% thu t c a b n gi&i n m c nào.
' ây có các ch
ã
c các l p
trình viên úc rút ra, các ch
này
áng gi i thích và cân nh c thêm,
ây là các ch
không
c ng (i
dùng yêu c u và s d ng.
H th ng tr giúp n n Eclipse cho phép b n s d ng i m m
r ng org.eclipse.help.contributions
óng góp trình b sung c a
mình vào tr giúp tr c tuy n. B n có th óng góp tr giúp tr c
tuy n nh là m t ph n c a trình b sung mã c a b n ho c c ng có
th cung c p nó m t cách c l p trong trình b sung tài li u c a chính nó. Vi c có trình b sung tài li u c a
riêng b n em l i l i ích trong vi c làm vi c v i b n sao c a mã ngu n và quá trình sinh tham chi u c l p
v i quá trình phát tri n. Có th có l i khi cân nh c n cách ti p c n này trong các tình hu ng nh v y, khi mà
i phát tri n khác v i i làm tài li u ho c khi b n mu n gi m
ph thu c gi a ngu n tài li u và mã ngu n.
!i m m r ng org.eclipse.help.contributions cung c p b n ph n t , qua các ph n t này b n có th óng góp
các tr giúp c a mình: t p thông tin các ch
(sách), các hành ng xem thông tin (l i). Các óng góp t p
thông tin ho c hành ng ch" ra m t t p .xml liên k t, t p này ch a các chi ti t c a vi c óng góp.
Thi t k các ràng bu c
B n có th ch y JavaTOC doclet t o ra các t p nh h ng
XML m c l c và Javadoc, ho c ch y công c
t o ra các t p
nh h ng XML m c l c và dùng Javadoc ã
c l p trình viên
t o ra. Bài vi t này trình bày gi i pháp s d ng chu n Javadoc
Generation wizard t o ra Javadoc cho tài li u tham chi u
Java API và JavaTOC doclet cho các t p nh h ng XML m c
Cho dù b n là m t th ký k$ thu t có
k$ n ng hay là m t l p trình viên thì
b n u mu n cung c p cho ng (i dùng
các tham chi u Java API ã
c t o tài
Tài li u tham chi u Java API
l c trong môi tr (ng phát tri n Eclipse.
Page 2 of 21
li u
y
, d dàng tìm ki m và duy t.
Bài vi t này trình bày cách ch y JavaTOC doclet trong Eclipse
thông qua th thu t Custom doclet, và th hai thông qua h th ng xây d ng Ant. N u b n ch a t)ng làm vi c
v i Ant, hãy xem trang Web Jakarta, ho c "Open Source Java: Ant" (Mã ngu n m Java: Ant).
Lu ng công vi c
Thêm các công c t o trình b sung JavaTOC (JavaAPITools) vào không gian làm vi c c a b n:
Hãy tìm th m c không gian làm vi c mà phiên b n Eclipse c a b n s d ng. Thông th (ng thì th
m c này
c t trong th m c mà trong ó Eclipse ã
c cài t trong m t th m c con có tên g#i
là "workspace". N u b n ang s d ng (ng d*n t t ho c k ch b n g#i Eclipse, thì nó s trong
th m c làm vi c hi n t i mà (ng d*n t t hay k ch b n c a th m c ó trong m t th m c con có
tên g#i là "workspace".
T i v và gi i nén gói ó (JavaAPITools) vào không gian làm vi c c a b n. Vi c này s t o ra d án
"JavaAPITools".
N p d án "JavaAPITools" và d án Java mà b n mu n làm vi c v i vào không gian làm vi c Eclipse
c a b n.
S d ng th thu t n p vào (Import Wizard) n p m t d án Java ã có s+n vào không gian làm vi c. V i ví
d
ây, tôi ã t o ra m t d án Java m i "org.dita.dost" và thêm vào mã ngu n (th m c src) t) mã ngu n
) thành các nh d ng có
DITA Open Toolkit , mã ngu n này bi n i n i dung DITA (các ánh x và ch
th phát
c. B n có th t i trình b sung này v t) các ngu n t i v .
T o tài li u Javadoc b ng cách s
Eclipse Javadoc (Doclet chu n)
Các b c ti p theo h
phát tri n Eclipse:
d ng th thu t t o
ng d*n b n cách s d ng Javadoc Doclet chu n
t o ra Javadoc trong môi tr (ng
Trong Eclipse, khung bên trái, ch#n trình b sung mã ngu n mà ta c n t o Javadoc cho nó.
Nh n chu t ph i vào trình b sung ã
c ch#n và ch#n Export t) danh sách th xu ng. C a s
Export m ra.
Ch#n Javadoc và nh n Next. C a s Generate Javadoc m ra.
Trong c a s Generate Javadoc ch#n các gói mà b n mu n xu t sang t p JAR. Danh sách này
c
kh i t o b,ng vi c ch#n workbench. M-i l n ch"
c ch#n m t d án b i vì khi ch y công c Javadoc,
m-i l n ch"
c s d ng m t (ng d*n l p d án. (Hình 1).
Ch#n tính hi n th các thành viên (thông th (ng Package và Public).
Ch#n S d ng Doclet chu n b t u l nh Javadoc v i doclet chu n (ng m nh).
c sinh ra vào ó. !ích là m t i s
Destination: ch#n ích mà doclet chu n s vi t tài li u
riêng cho doclet và vì v y nó không
c kích ho t khi s d ng doclet tùy bi n.
ích mà doclet chu n s vi t vào có th ví d là "doc.dita.dost.doc\topics" (Hình 2)
Hình 1. Th thu t sinh Javadoc (Doclet chu n)
Tài li u tham chi u Java API
Hình 2. ích
Page 3 of 21
Tài li u tham chi u Java API
B ng các tùy ch n tr giúp
Page 4 of 21
c cung c p b i th thu t sinh Javadoc:
Tùy ch n
Mô t
Tiêu
Ch" ra m t tiêu
tài li u
tài li u.
Generate use page (sinh
ra trang s d ng)
Ch#n tùy ch#n này n u b n mu n tài li u ch a
m t Use page (trang s d ng).
Generate hierarchy tree
(sinh ra cây th b c)
Ch#n tùy ch#n này n u b n mu n tài li u ch a
m t Tree page (trang cây).
Generate navigator bar
(sinh thanh nh h ng)
Ch#n tùy ch#n này n u b n mu n tài li u ch a
m t thanh nh h ng (ph n u và ph n cu i).
Generate index (sinh
ch" m c)
Ch#n tùy ch#n này n u b n mu n tài li u ch a
m t trang ch" s
Generate index per
letter (sinh ch" m c cho
m-i kí t )
T o ch" s cho m-i kí t . Tùy ch#n này
c
kích ho t khi "Generate Index" (sinh ch" s )
c ch#n.
@author
Ch#n tùy ch#n này n u b n mu n th. @author
c làm tài li u.
@version
Ch#n tùy ch#n này n u b n mu n th. @version
c làm tài li u.
@deprecated
Ch#n tùy ch#n này n u b n mu n th.
Tài li u tham chi u Java API
Page 5 of 21
@deprecated
c làm tài li u, tham chi u
m t m c l c, ví d nh
n
deprecated list (danh
sách không tán thành)
L a ch#n tùy ch#n này n u b n mu n tài li u
ch a m t trang không tán thành. Tùy ch#n này
c kích ho t khi tùy ch#n @deprecated
c
ch#n.
Ch#n các l p tham
chi u mà Javadoc c n
t o liên k t t i
Ch" ra là Javadoc c n t o liên k t t i tài li u nào
khác khi mà các ki u khác
c tham chi u.
Ch#n t t c : T o liên k t t i t t c các
vùng tài li u khác
Xóa t t c : Không t o liên k t t i các
vùng tài li u khác
! nh c u hình: ! nh c u hình vùng
Javadoc c a JAR tham chi u ho c d án
Style sheet (trang ki u)
Ch#n trang ki u s s d ng
Nh n Finish
t o Javadoc, ho c nh n Next
ch" ra thêm các tùy ch#n sinh Javadoc.
GHI CHÚ: ! bi t thêm chi ti t hãy xem Javadoc generation — Eclipse Help Platform (Sinh Javadoc - N n
tr giúp Eclipse)
Th
m c ích c a các t p
u ra
Doclet sinh ra các t p HTML u ra cho tài li u trình b sung t i
"org.dita.dost\org.dita.dost.doc\topics\", bây gi( ây chính là th m c tài li u trình b sung c a b 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)
Các b c sau ây th hi n cách s d ng doclet tùy bi n, JavaTOC doclet, k t h p v i Javadoc trong môi
tr (ng phát tri n Eclipse:
Trong Eclipse, khung phía bên trái, ch#n trình b sung mã ngu n mà c n sinh Javadoc cho nó.
Nh n chu t ph i t i trình b sung ã ch#n, và ch#n Export t) danh sách th xu ng. C a s Export s
m ra.
Ch#n Javadoc và nh n Next. C a s Generate Javadoc s m ra.
Trong c a s Generate Javadoc ch#n các gói mà b n mu n xu t sang t p JAR. Danh sách này kh i t o
b,ng vi c ch#n workbench. M-i l n ch" có th ch#n m t d án b i vì khi ch y công c Javadoc, m-i l n
ch" có th s d ng m t (ng d*n l p d án.
Ch#n tính hi n th c a thành viên (thông th (ng Package và Public).
Ch#n Use Custom Doclet (S d ng doclet tùy bi n) và thêm các tên ki u doclet
tiêu chu n vào tên
Doclet: com.ibm.malup.doclet.config.DITADoclet , và (ng d*n l p mà l p doclet c n vào (ng
d*n l p Doclet: <eclipse_workspace>\JavaAPITools\bin\JavaTOC.jar
GHI CHÚ: <eclipse_workspace> là (ng d*n tuy t i cho không gian làm vi c Eclipse
(C:\eclipse\workspace).
c sinh ra vào ó. !ích là m t i s
Destination: ch#n ích mà doclet chu n s vi t tài li u
Tài li u tham chi u Java API
riêng c a doclet và vì v y nó không
c kích ho t khi s d ng doclet tùy bi n.
ích mà doclet chu n s vi t vào có th
c ví d là "doc.dita.dost.doc\topics"
Nh n Next.
Hình 3. Th thu t sinh Javadoc (Doclet tùy bi n)
Hình 4. ích
Page 6 of 21
Tài li u tham chi u Java API
Các tùy ch n Javadoc m
Page 7 of 21
r ng
V i các tùy ch#n Javadoc m r ng (các tên (ng d*n v i các kho ng cách tr ng ph i
c t trong
các d u nháy); thêm n i dung t) ví d 1 (v i ví d c a chúng ta là trình b sung org.dita.dost).
1. -d <destination_directory> Ch" ra th m c ích cho tài li u
c sinh ra. Theo ng m nh thì
nó là th m c hi n t i (th m c
c thi t k b i tên (ng d*n ".").
2. -pluginid <plugin_id> Bao g m ch" s c a trang ch" s trình b sung Eclipse.
3. -doctitle <html_code> Bao g m tiêu c a trang tên trình b sung Eclipse.
4. —overview <file> Ch" ra các chi ti t ch" s phiên b n trình b sung.
5. —version <plugin_version> Ch" ra các chi ti t ch" s phiên b n trình b sung.
6. -provider <plugin_provider> Ch" ra các chi ti t tên nhà cung c p trình b sung.
7. -anchor <file> Vi c liên k t
c ch" ra b,ng cách s d ng các tham chi u có y
i u ki n
t i m t m c l c, ví d nh : "../the_other_plugin_id/path/to/toc.xml#anchor_id"
8. -notree N u b n nh t o tài li u cho m t d án l n, ch" ra là b n s t o nhi u t p m c l c XML.
Ví d 1. Các tùy ch n Javadoc m r ng
!
" #
$
Tài li u tham chi u Java API
Th
m c ích cho các t p
Page 8 of 21
u ra
Doclet t o ra các t p XML m c l c u ra cho trình b sung, và m t s các t p h u d ng khác trong th
m c org.dita.dost\org.dita.dost.doc\, hi n nay ó chính là th m c trình b sung c a b n. Các t p
c t o ra b i JavaTOC doclet là:
plugin.xml
plugin.properties
build.properties
.project
META-INF\MANIFEST.MF
primary.plugin.toc.xml
org.dita.dost.xxx.toc.xml— t p XML m c l c xây d ng lên cây nh h ng trong trình duy t
tr giúp
Các giá tr tên, ch s , phiên b n, và tên nhà cung c p c a trình b sung
ct
ng sinh ra t) các
thu c tính -d, -doctitle, —version và —provider.
Các t p b ng kê trình b sung m r ng các xâu c a chúng b,ng cách thay th xâu v i m t khóa (ch/ng
h n nh %pluginName) và t o ra m t m c vào trong t p plugin.properties c a bi u m*u: Plugin.name
= Online Help Sample Plugin
S d ng JavaAPITools (build.xml & JavaTOC doclet) và
ANT
t o trình b sung tài li u c a b n
M c ích chính c a JavaAPITools là t o ra trình b sung NEW DOCUMENTATION (Tài li u m i) v i
Javadoc cho tài li u tham chi u API công khai và t t c các t p trình b sung Eclipse c n thi t tích h p tài
li u tham chi u Java API này v i h tr giúp Eclipse, ngo i tr) các t p nh h ng XML m c l c cho
Javadoc.
Cài
t các công c xây d ng trình b sung (buildAPITools)
Gói JavaAPITools cung c p k ch b n xây d ng Eclipse cho vi c t o các trình b sung tài li u Eclipse. K ch
b n cho phép b n chuy n i các trình b sung d án Java trong Eclipse và s d ng th(i gian ch y theo m c
tiêu t ra c a Eclipse ki m tra chúng. Hoàn thành vi c t o ra Javadoc b,ng cách t o ra m t k ch b n ANT
trong trình b sung c a b n có tên g#i là build.xm. K ch b n ANT này yêu c u các công c xây d ng
build.xml JavaAPITools ph i
c t âu ó trong h th ng phát tri n (không gian làm vi c) c a b n. K ch
b n ó c ng ph i có th xác nh
c cách trình b sung xxx.doc k t qu
c óng gói tri n khai.
T i gói ó v , t o d án 'JavaAPITools' trong không gian làm vi c c a b n, và gi i nén gói ó vào d
án.
N p các trình b sung mà b n mu n làm vi c v i vào trong không gian làm vi c Eclipse c a b n. Trong
ví d này tôi ã t o ra m t d án Java m i và ã thêm th m c src th m c ngu n t) mã ngu n DITA
) thành các nh d ng có th
Open Toolkit mã ngu n này bi n i n i dung DITA (các ánh x và ch
phát
c. B n có th t i v trình b sung này t) các ngu n t i v , ho c b n có th ch y trên ví d d
án c a mình.
Xác
nh vi c óng gói tri n khai trình b sung
Các phiên b n tr c Eclipse 3.2, Javadoc sinh ra s
c l u trong m t t p doc.zip cùng v i các t p HTML.
K t) phiên b n 3.2, toàn b các trình b sung tài li u có th
c a vào m t t p .jar 0n, t p này ch a t t c
các t p s
c a vào t p doc.zip, cùng v i các t p trình b sung Eclipse: manifest.mf, plugin.xml,
plugin.properties, v.v..
Tài li u tham chi u Java API
Page 9 of 21
K t) Eclipse 3.1, các trình b sung có th
c tri n khai nh là m t th m c ch a các t p riêng r (bao g m
m t ho c nhi u các t p jar) ho c nó c ng có th
c tri n khai nh là m t t p jar 0n.
Ví d 2. build.properties
"
% !&
'()*
*
,$ *
,$ *
+
*
"
)
*
c tri n khai nh là m t th m c thì t p build.properties nên ch a
L i bình: N u nh trình b sung g c
t p doc.zip. N u trình b sung
c tri n khai nh là m t t p .jar 0n thì build.properties KHÔNG nên ch a
doc.zip nh ng nên ch a th m c droot và các t p ã
c t o ra trong t p doc.zip.
Thêm vào ó, trình b sung doc-feature ch a m t trình b sung doc nh v y c ng ph i có thu c tính
unpack="false" trong t p feature.xml c a trình b sung.
T o, qu n lý và ch y t p xây d ng ANT
Nh n chu t ph i build.xml t) builAPITools và ch#n Run As > External Tools, và trong ph n
Builders ch#n New Lunch Configuration .. và t o ra m t c u hình xây d ng Ant m i.
Trong h p tho i c u hình k t qu , t tên là m t cái gì ó duy nh t (ví d Build Plugin Documentation).
Trong th. Main c a ph n t i c u hình, duy t không gian làm vi c và ch#n t p build.xml t)
JavaAPITools). Thêm vào th m c Base giá tr : ${project_loc}.
S0
sau ây, hình 5, th hi n th. Main c a h p tho i c u hình t i ANT.
Hình 5. Cài
t
ch y t p xây d ng ANT
Tài li u tham chi u Java API
Các
Page 10 of 21
is :
! i s —verbose cho phép b n l n theo thông tin v m t l nh c th hi n ang không làm vi c.
! i s —quiet ch n l i h u h t các thông i p không b t ngu n t) nhi m v báo hi u trong t p
ã xây d ng s+n, và -debug, in ra các thông tin s a l-i trong b ng i u khi n Eclipse.
! i s —Dbuild.toc.tree=true ghi è thu c tính —build.toc.tree và gán giá tr là true tr c khi
k ch b n xây d ng
c th c hi n. Vi c này s ch" t o m t t p XML m c l c chính
(xxx.toc.xml) thay vì nhi u t p.
T o t p ANT build.xml
K ch b n build.xml nh ngh%a t t c các thông tin c n thi t t o ra Javadoc cho các trình b sung thành
ph n k t h p và t o ra t p doc.zip ho c sao chép các t p ã
c t o ra vào g c c a trình b sung. ! hoàn
thành tài li u v các nhi m v s
c s d ng trong t p này hãy xem JavaAPITools/build.xml.
N i dung kh i t o cho t p này s là:
Ví d 3. build.xml
./,$
.4
.4
.4
.4
.
%0
0
%01 ( 20/3
55555555555555555555555555555555555555555555555555555555555555
6 ,7# 6
'
8
9
6 $6
6 &
: 9
; 8 "6
!
) 2)< =
55555555555555555555555555555555555555555555555555555555555555
+
.
$ %0"
8 $
0
>
%0?@
%0$
03
+
$ A
?@
>
A0)3
3
:
3
3
6
3
Tài li u tham chi u Java API
Page 11 of 21
.4
5555555555555555555555555555555555555555555555555555555555555555555555555555
!6
B ,7# 6
8C 8
5555555555555555555555555555555555555555555555555555555555555555555555555555
3
.
$ %0$
0
%0
*
!
>
!(*
D
E!F* " D
*
G
*
G
H
*
#D
*
#D
*
D +
0
%0
D
$
03
. 8 $
%0?@
+
$ A ?@
>
A0)3
.)
3
F6 ";
"; 8
IC 8 0 8C 80 86
8
9 JC 8
8 6
C 8 86 8 6
8
6
6 , 6 8 6
6
8K
L 6
9
86 M
6
86 6 *
66
86 $6 JC 8 J66
86
8
6$ 86
8
N $6 JC 8 6$ 86
86 8 6
:
N : 8 :
:
N 86 ,6#
L
*
!
>
!(*
D
E!F* "
*
G
*
G
H
*
O *
#D
*
D +
M
.
$ %0
0
.
.
.
.
.)
3
.
.)
F6
$ %0
0
%0
0
.
$ 3
.> $
#%0
0
.)
$ 3
. 8 3%%% P
D
. 8 3%%% ?@
A %%%.) 8 3
%0P
%0
8
D
+
03
!!!! #### RR $$
$
%%%.)
0 )3
8 3
3
";
"; 8
6 ,7# 6
8K
JS J66
.
%0D +
"
03
$ %0& F DP&QRH!&0
%0 ) )0)3
$ %0"
0
%0+ 0)3
$ %0
+
0
%0?@"
A0 )3
$ %0"
0
%0>
0 )3
#
#
#
#
6
J6 8
8T
$ %0
#
6
8U
D
6
V
6
6
0
#%0
"
>
.
.)
,$
,
%0?@
+
,$
03
A
86
$
86
>
86
:
$>03
,$ 0 )3
3
.
.
.)
"
#%0$
>
>
$> ,
%0?@
+
03
A !&
'()! ' (&P
!(0 )3
3
.
#%0
.
.)
.
.)
.)
3
.)
03
3
.
.
C 8 86
#3
%0P
.
.)
6 9
8 6
$6 .
W
3
.
#%0
.
#%0$
,$
,
0 )3
3
3
>
$>
,
0 )3
3
3
3
$ %0
!
>
!(0
%0
>%0$
>
.
.>
D
$> ,
%0X
(
%0?@
8
3
.
0
0
$
+
> $ ! ' (&P !( 03
A !&
'()! ' (&P !(03
3
.
.)
.
.
.
%0
0 )3
3
>
>
>
$%0Y0
$%0 0
$%0
%0
0 )3
%00 )3
%
0
%00
)3
Tài li u tham chi u Java API
Page 12 of 21
.)>
8
.)
.
.
.
.
.
.)
3
3
#
$ %0
$ 0
%0?@
+
$ 0
$ 0
$ 0
(
#
#
#
$ %0"
$ %0
$ %0
$ %0
> ! ' (&P
D
!(
E!F0
%0
>%0
%0$
,
.,$
.
.
.
.
.)
D
,$
>
%0X
03
# >
%0?@
$ %0
$ %0"
$ %0
$ %0
#
#
#
#
$ %0"
.>
D
+
$ 0
$ 0
$ 0
$ 0
,$
.)
$
0 )3
>
3
";
"; 8
,7# 6
6
6 6
B * 86 6* B
8 "6
G
N 6
6 , 6 8 6
"6
86 8U
N 6
$ %0
.
.+
$
A
,$
,$ 0 )3
L MA
L"
L"
L"
%0?@
%0?@
%0?@
%0?@
D
G
%0&[[H[
# 6
6
8 B "6
0 )3
$ MA0 )3
MA0 )3
MA0 )3
0
%0D
D
6
:
B
>
?@
03
+
! ' (&P
8:
J 6
8 6
6 "6
,$ 8 # ! ' (&P !(
A
!( 8 6 ) :
6
6
:
J66
;$
6
6
; 8 "6
,$ *
N 6
6
86#
0
D
8 3P1
&PP
8
0
0
G
%0?@
%0?@
# ?@"
%0 "
0
%0
0
%0?@
%0>
%0>
%0
.
>
0
%0X
.$
.$
8B$
0
$
0
%0
%0
I6
0
,
$>
%0
.)
F6 ";
"; 8
E $ "6
8B$ :
0
,
>%0
.
%0?@
%0?@
%0?@
3
.
F6
6
:
;
F6
6
P#$"
' $ A0 )3
'()! ' (&P !(0)3
' $ A0 )3
Z
A0 )3
Z
A0 )3
A !&
3
.
'
%0?@
$
\0
8%0
,%0
D
$
$ A0 )3
$ A)!&
A ?@
$ A
0
%0>
03
'(0 )3
$ A.)
8 3
0
0
,%0>
0
"
%0>
"6
$ 6
0
0
%050
0
0
%0
0
%0
0)3
3
9
9
W#
W#
B
86
86
86
J6
ZC
ZC 6
6 L]
]
9
$ %0
G
6 J66
86# G
8
M
H
6 "6
8 6
:
:
6
#
8 3&
8;
%0X
D
$ %0"
D8
.4
P
.
#
0
8 G
8
%0
E!F H >
)G
D
D8
%0
P
(
$ %0
3
.+
"
8B$
0
&
.
%0
8 6
6
0
0
%0
.
.
86
0
8%0 0
0
%0?@
+
%0?@D
03
)"
)G
G
H
+ 0 )3
.) 8 3
A
0)3
Q
A0 )3
Tài li u tham chi u Java API
8%0
%0?@"
Page 13 of 21
0
A0
$
%050 3
.
$ %0 $
8%0?@"
.
$
.
$
.
$
.
$
.
$
.)
0
$ A0)3
L?@"
$ A0)3
$ A0)3
$ A0)3
$ AM0)3
A0)3
3
.)+
.)
F6 ";
"; 8
E $ C 6
86# U
"$ $
>
H
D
A03
$ %0 0
%0?@"
A ?@
$ %0
0
%0 D [ >
$ %0
0
%0?@
$ %0
0
%0?@
$ %0
0
%0?@
.4
.
$
$ %0
8 0
%0?@
3
3
3
9
6 G
.
$
$ %0
.
.
$
$ %0
$ %0
#%0"
W#
H
ZC
86
6
0
G
$6
^
6
.>
%0?@"
ZC
ZC 6
8 0
#D
^
.
>
8
%0
6
3
"6
$ 6
A ?@
.>
3
) 8 Q 8
8B$
9
$ A
Q
Q
)
W#
86
J6
8 $ 0)3
8)
)
,$ _
8
Q
Q
%0 >
%0?@"
(
# L
A)"
#%0
#D
%0?@"
.
.)
.)
.
3
$ %0
O
>%0
%0
O
0 3
Q
A0
"
%0
. 8 3%% 8
.>
$ A03
.
.
.
.
.)- 3
.
%0?@
.)
.
0
#D
0
$ %0
6
86 $6
#D
#
8 6
.
+
$
$
$
$
A ?@
#03
# %%.)
-
%0?@
6
$6
6
6
6 "
G [M
+
A ?@
:
6
6
%0
# 8
+
$ #
%0
0
)?@
$ A03
$ A0 ,
%055)5
3
:#
3
8 3
0
%0
)550 )3
%0 $
)550 )3
%0 >)550 )3
%05
0 )3
$ A)
L 6
-
0 )3
; 8 "6
:
J66
03
8* 55)"
$ %0
D +
0
%0
8
+
03
.
%0?@
+
A ?@
$ A0 )3
.
%0 )"
D
)?@
$ A0 )3
. 8 3%%% &
?@
$ A D
$
. 8 3%%%
?@
A
%%%.) 8 3
.)
+
%0?@
#
$ A)
0
.
#
%0?@& F DP&QRH!&A)
.>
%0?@
.)
#3
.)
3
.)
"
3
86 $6
F6 ";
"; 8
8`
6 9
0)3
0 )3
%0 8
";
"; 8
,7# 6
6
8
-
3
.
F6
6
M03
0
0 )3
.
"
0)3
0
8U
:$
6
6
"6
G
"
0)3
%%%.)
8 3
Tài li u tham chi u Java API
T
Page 14 of 21
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.
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.
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.
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.
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 0n, 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" />
.project
plugin.xml
plugin.properties
META-INF\MANIFEST.MF
topics\ — All HTML files.
doc.zip
primary.plugin.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.bat — T p BAT
ch y công c JavaDoc.
<property name="build.toc.tree"
value="true" />
.project
plugin.xml
plugin.properties
META-INF\MANIFEST.MF
topics\ — All HTML files.
doc.zip
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.bat — T p BAT
ch y công c 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:
' d án Java plugin.properties thêm Plugin.notree = false
Tài li u tham chi u Java API
D
D
D
D
D
$
%
Q
8
Page 15 of 21
' $ %
%
) $
Q
%
% >
!
"$ ,
$
)
$
#
,$ _
' build.xml thêm
.
(
.
%0?@
+
#
A
$ %0
0
0)3
%0?@D
Q
A0 )3
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)
c a b n.
n p trình b sung tài li u vào không gian làm vi c
T) thanh th c 0n 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
Tài li u tham chi u Java API
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
Page 16 of 21
Tài li u tham chi u Java API
Page 17 of 21
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:
Ch#n Window > Preferences > Plug-in Development > Target Platform
! 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).
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.
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.
' 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
Trong Program to Run, ch#n Run a product và ch#n org.eclipse.platform.ide
' th. Plug-ins, ch#n Choose plug-ins and fragments to launch from the list
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.
! nguyên danh sách External Plug-ins nh v y.
Ch#n h p ki m Add new workspace plug-ins to this launch configuration automatically.
Nh n Apply ghi l i các thay i.
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,
Tài li u tham chi u Java API
nh ng s có m t b n sao c a các trình b sung c
ph m.
GHI CHÚ: M t khi b n ã ch y trình b sung c
s xu t hi n trong l ch s ch y, vì v y b n có th
Run History > Test Plugin Doc, ho c b n có th
Page 18 of 21
c b c a b n thay vì phiên b n trong s n
a mình, c u hình ch y (Test Plugin Doc)
kh i ch y th(i gian ch y ích v i Run >
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à .
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
b sung c a mình ã
c thêm vào (t 0ng t nh trong hình 2).
Hình 9. Help — Eclipse SDK
c c a s tr giúp, hình 9, v i trình
Tài li u tham chi u Java API
Page 19 of 21
ó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.
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.
K t lu n
JavaTOC Doclet
c trình bày trong tài li u này có th
cs
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.
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.
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 0n 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
ct 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 h0n 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ó.
Các t i v
Mô t
Tên
Kích th
c
Ph
ng th c t i
Tài li u tham chi u Java API
Page 20 of 21
JavaTOC doclet
JavaAPITools.zip
261KB
HTTP
Ví d JavaTOC
org.dita.dost.zip
323KB
HTTP
Thông tin v ph 0ng th c t i
Tài nguyên
H ct p
Tìm hi u thêm v công c Sun Microsystems Javadoc.
Xem trang ch c a Javadoc có thêm thông tin v công c Sun Microsystems 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.
The 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 m1o 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 0ng 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 Javadoc generation 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.
và
DITA Open Toolkit là m t th c thi c a c t thu c y ban k% thu t OASIS DITA cho các l c
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 c0 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
r ng c t tham chi u API chung.
c s d ng ho c xem xét nh là m t ví d v cách m
Tài li u tham chi u Java API
Page 21 of 21
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"
ôi nét v tác gi
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 k2 h#p “Beyond the Bleeding Edge” (v t trên các m i nh#n công ngh ) vào n m
2005