Tài liệu tham chiếu Java API

Phần 3: Cấu trúc tham chiếu Eclipse Javadoc API được tạo ra thông qua việc chạy JavaTOC doclet và ANT

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.

Mariana Alupului, Phát triển Thông tin, Rational software, IBM

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


Cấp độ đóng góp cho developerWorks của
        tác giả

10 07 2009

Ô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.

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.

Sử dụng JavaTOC doclet để sinh trình bổ sung Eclipse (tài liệu tham chiếu Javadoc API)

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

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 liệu đầy đủ, dễ dàng tìm kiếm và duyệt.

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 lục trong môi trường phát triển Eclipse.

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 DITA Open Toolkit, mã nguồn này 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. 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ử dụng thủ thuật tạo Eclipse Javadoc (Doclet chuẩn)

Các bước tiếp theo hướng dẫn bạn cách sử dụng Javadoc Doclet chuẩn để tạo ra Javadoc trong môi trường phát triển Eclipse:

  • 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 PackagePublic).
  • Chọn Sử dụng Doclet chuẩn để bắt đầu lệnh Javadoc với doclet chuẩn (ngầm định).
    • Destination: chọn đích mà doclet chuẩn sẽ viết tài liệu được sinh ra vào đó. Đích là một đối số 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)
Javadoc Generation Wizard (Thủ thuật sinh Javadoc)
Hình 2. Đích
Chụp màn hình đích
Bảng các tùy chọn trợ giúp được cung cấp bởi thủ thuật sinh Javadoc:
Tùy chọnMô tả
Tiêu đề tài liệu Chỉ ra một tiê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ẻ @deprecated được làm tài liệu, tham chiếu đến một mục lục, ví dụ như
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.

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 PackagePublic).
  • 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).
    • Destination: chọn đích mà doclet chuẩn sẽ viết tài liệu được sinh ra vào đó. Đích là một đối số 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)
Thủ thuật sinh Javadoc (Doclet tùy biến)
Hình 4. Đích
Chụp màn hình đích

Các tùy chọn Javadoc mở 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
-d C:\eclipse\workspace\org.dita.dost\org.dita.dost.doc\
-pluginid org.dita.dost.doc
-doctitle 'Building DITA output' 
-version '7.0.0.1' 
-provider 'IBM' -subsystemtoc

Thư mục đích cho các tệp đầ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 được tự động sinh ra từ các thuộc tính -d, -doctitle, —version—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 Open Toolkit mã nguồn này 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. 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 đơn, 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..

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 đơn.

Ví dụ 2. build.properties
bin.includes = META-INF/,\
               .project,\
               plugin.xml,\
               toc.xml,\
               plugin.properties,\
               doc.zip,\
               bin/

Lời bình: Nếu như trình bổ sung gốc được triển khai như là một thư mục thì tệp build.properties nên chứa tệp doc.zip. Nếu trình bổ sung được triển khai như là một tệp .jar đơn 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}.

Sơ đồ 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
Cài đặt để chạy tệp xây dựng ANT
  • Các đối số:
    • Đố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
<?xml version="1.0" encoding="UTF-8"?>

<!-- **************************************************************  -->
<!-- Tệp xây dựng ANT cho các tệp mục lục Eclipse và các trình bổ sung tài liệu -->
<!-- Mariana Alupului 10/08/2006                                     -->
<!-- **************************************************************  -->

<project name="build" default="main">
	<echo message="${ant.project.name}: ${ant.file}"/>
	
	
<!-- **************************************************************************** Mục tiêu xây dựng chính. **************************************************************************** --> <target name="main" depends="setup, useManifestMF, usePluginXML, badPlugin, runJavaDoc, runJavaTOCDoclet, deployPlugin, copyPlugin, cleanProject" description="Build Plug-in Documentation"> <echo message="${ant.project.name}: ${ant.file}"/> </target>
Lời bình: Đích "chính" thực thi các đích trong thuộc tính phụ thuộc theo trật tự xuất hiện của chúng (từ trái sang phải). Cần nhớ rằng, trường hợp một đích được thực thi sớm hơn khi có một đích sớm hơn phụ thuộc vào nó là hoàn toàn có thể xảy ra: (setup, useManifestMF, usePluginXML, badplugin, runJavaDoc, runJavaTOCDoclet, generateZip, copyPlugin, cleanProject).

<target name="init" description="Project variables"> <property name="ECLIPSE_HOME" value="../../"/> <property name="build.plugin" value="jar"/> <property name="project.dir" value="${basedir}" /> <property name="build.toc.tree" value="false" /> </target> <target name="setup" depends="init" description="Setup the Project"> <tstamp> <format property="now" pattern="d MMMM yyyy HH:mm:ss aa" /> </tstamp> <echo>=== Starting Building Plugin Documentation ===</echo> <echo>=== ${now} ===</echo> </target> Lời bình:
Tệp xây dựng Ant cung cấp truy cập tới tất cả các thuộc tính hệ thống như thể là chúng đã được định nghĩa thông qua việc dùng một <property> task.

<target name="validatePlugin" description="Select plugin.xml or manifest.mf"> <condition property="plugin.xml.exists"> <available file="${project.dir}\plugin.xml" /> </condition> <condition property="manifest.mf.exists"> <available file="${project.dir}\META-INF/MANIFEST.MF" /> </condition> <condition property="invalid.plugin"> <and> <not> <isset property="plugin.xml.exists" /> </not> <not> <isset property="manifest.mf.exists" /> </not> </and> </condition> </target> <target name="useManifestMF" depends="validatePlugin" if="manifest.mf.exists" description="Get plugin name from MANIFEST.MF "> <loadproperties srcFile="${project.dir}\META-INF/MANIFEST.MF"> <filterchain> <linecontains> <contains value="singleton" /> </linecontains> <replacestring from=";" to=".doc" /> <replacestring from=" " to="" /> <replacestring from="singleton:=true" to="" /> </filterchain> </loadproperties> <property name="plugin.name" value="${Bundle-SymbolicName}" /> <loadproperties srcFile="${project.dir}\META-INF/MANIFEST.MF"/> <property name="bundle.name" value="${Bundle-Name}" /> <property name="version.name" value="${Bundle-Version}" /> <property name="vendor.name" value="${Bundle-Vendor}" /> </target> <target name="usePluginXML" depends="validatePlugin" if="plugin.xml.exists" unless="manifest.mf.exists" description="Get plugin name from plugin.xml if MANIFEST.MF does not exist "> <xmlproperty file="${project.dir}\plugin.xml" /> <property name="plugin.name" value="${plugin(id)}.doc" /> <property name="bundle.name" value="${plugin(bundle-name)}" /> <property name="version.name" value="${plugin(bundle-version)}" /> <property name="vendor.name" value="${plugin(bundle-vendor)}" /> </target> <target name="badPlugin" depends="validatePlugin" if="invalid.plugin" description="Processing ends if plugin is invalid "> <fail message="ERROR::Plugin ${project.dir} is invalid. No plugin.xml was found." /> </target> Lời bình: Tệp xây dựng Ant cung cấp truy cập tới tệp MANIFEST.MF hoặc/và tới tệpplugin.xml, và sử dụng tên, chỉ số, tên phiên bản và tên nhà cung cấp của trình bổ sung có sẵn từ trình bổ sung Java có sẵn.
Lỗi sẽ xuất hiện trong bảng điều khiển của bạn nếu như không có tệp plugin.xml hay MANIFEST.MF nào được tìm thấy.

<target name="runJavaDoc" depends="validatePlugin" unless="invalid.plugin" description="Generate JavaDoc API documentations"> <mkdir dir="${plugin.name}" /> <mkdir dir="${plugin.name}/META-INF" /> <echo>SUCCESS: Create directory ${basedir}\${plugin.name}</echo> <javadoc access="public" author="true" destdir="${plugin.name}\topics" nodeprecated="false" nodeprecatedlist="false" noindex="false" nonavbar="false" notree="false" packagenames="*" source="1.4" sourcepath="src" splitindex="true" use="true" version="true"/> </target> Lời bình: Xem bảng các tùy chọn hỗ trợ được cung cấp bởi thủ thuật sinh Javadoc nếu bạn muốn thêm vào các tùy chọn để chạy Javadoc chuẩn.

Ví dụ: Để thêm tên tác giả (@author ) vào tài liệu thì thêm author="true" .

<target name="runJavaTOCDoclet" unless="invalid.plugin" description="Generate Eclipse XML TOC files"> <property name="buildAPITools" value="../JavaAPITools/bin/JavaTOC.jar" /> <echo>End Phase I Standard Doclet - Start Phase II JavaTocDoclet...</echo> <!-- <loadproperties srcFile="${project.dir}\plugin.properties"/> <property name="plugin.link" value="${Plugin.link_to}" /> --> <javadoc access="public" classpath="." sourcepath="src" notree="${build.toc.tree}" packagenames="*" > <doclet name="com.ibm.malup.doclet.config.TOCDoclet" path="${buildAPITools}"> <param name="-d" value="${basedir}\${plugin.name}"/> <param name="-plugintitle" value="API Reference (${bundle.name})"/> <param name="-pluginid" value="${plugin.name}"/> <param name="-version" value="${version.name}"/> <param name="-provider" value="${vendor.name}"/> <!-- <param name="-anchor" value="${plugin.link}"/> --> </doclet> </javadoc> </target> Lời bình: Xem ví dụ 1. các tùy chọn Javadoc mở rộng nếu bạn muốn thêm các tùy chọn để chạy công cụ JavaTOC doclet.

Ví dụ: —overview <file> <param name="-overview" value="${basedir}\${plugin.name}\overview.html"/>

Ví dụ: —anchor <file> <param name="-anchor" value="../the_other_plugin_id/path/to/toc.xml#anchor_id"/> <target name="deployPlugin" description="If plug-in is packaged as a directory (unpacked)"> <loadfile srcFile="${basedir}/build.properties" property="build_properties" /> <condition property="deployPlugin" > <contains string="${build_properties}" substring="doc.zip"/> </condition> <antcall target="createDocZip" /> </target> <target name="createDocZip" if="deployPlugin" description="The plug-in is packaged as a directory"> <echo>== The .doc plug-in is to be deployed as a directory ==</echo> <zip destfile="${project.dir}\${plugin.name}/doc.zip" basedir="${plugin.name}"> <include name="topics/**" /> <include name="images/**" /> <include name="pdf/**" /> <include name="*.css" /> </zip> <delete dir="${project.dir}\${plugin.name}/topics" /> </target> Lời bình: Tệp xây dựng Ant cung cấp truy cập tới tệp build.properties (nếu trình bổ sung được triể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}"> <fileset dir="${plugin.name}" excludes="**/*.launch, **/buildJavaDoc.bat"/> </copy> </target> <target name="cleanProject" description="Cleans the project"> <delete dir="${project.dir}\${plugin.name}" /> <delete dir="../buildAPITools/${plugin.name}" /> <echo>=== End Building ${plugin.name} Plug-in Documentation ===</echo> <echo>=== ${now} ===</echo> </target> Lời bình: Chép dự án này vào không gian làm việc của bạn.

</project>

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.
    • 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 đơ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" />
    • .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.
    • .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
      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
    • build.xml thêm

      <loadproperties srcFile="${project.dir}\plugin.properties"/>
               		<property name="plugin.link" value="${Plugin.link_to}" />

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
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
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
Nạp trình bổ sung vào không gian làm việc 3

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, 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ụ.Run
      • Run Build Plugin Docs
      • 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 đượ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
Lược đồ

Đó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

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ó.


Các tải về

Mô tảTênKích thước
JavaTOC docletJavaAPITools.zip261KB
Ví dụ JavaTOCorg.dita.dost.zip323KB

Tài nguyên

Học tập

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.

Thảo luận

Bình luận

developerWorks: Đăng nhập

Các trường được đánh dấu hoa thị là bắt buộc (*).


Bạn cần một ID của IBM?
Bạn quên định danh?


Bạn quên mật khẩu?
Đổi mật khẩu

Bằng việc nhấn Gửi, bạn đã đồng ý với các điều khoản sử dụng developerWorks Điều khoản sử dụng.

 


Ở lần bạn đăng nhập đầu tiên vào trang developerWorks, một hồ sơ cá nhân của bạn được tạo ra. Thông tin trong bản hồ sơ này (tên bạn, nước/vùng lãnh thổ, và tên cơ quan) sẽ được trưng ra cho mọi người và sẽ đi cùng các nội dung mà bạn đăng, trừ khi bạn chọn việc ẩn tên cơ quan của bạn. Bạn có thể cập nhật tài khoản trên trang IBM bất cứ khi nào.

Thông tin gửi đi được đảm bảo an toàn.

Chọn tên hiển thị của bạn



Lần đầu tiên bạn đăng nhập vào trang developerWorks, một bản trích ngang được tạo ra cho bạn, bạn cần phải chọn một tên để hiển thị. Tên hiển thị của bạn sẽ đi kèm theo các nội dung mà bạn đăng tải trên developerWorks.

Tên hiển thị cần có từ 3 đến 30 ký tự. Tên xuất hiện của bạn phải là duy nhất trên trang Cộng đồng developerWorks và vì lí do an ninh nó không phải là địa chỉ email của bạn.

Các trường được đánh dấu hoa thị là bắt buộc (*).

(Tên hiển thị cần có từ 3 đến 30 ký tự)

Bằng việc nhấn Gửi, bạn đã đồng ý với các điều khoản sử dụng developerWorks Điều khoản sử dụng.

 


Thông tin gửi đi được đảm bảo an toàn.


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=70
Zone=Công nghệ Java, Nguồn mở, Rational
ArticleID=407126
ArticleTitle=Tài liệu tham chiếu Java API
publish-date=07102009