Tài liệu tham chiếu Java API Phần 2

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, Phát triển Thông tin, Rational software, IBM Tóm tắt: 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...
Nội dung trích xuất từ tài liệu:
Tài liệu tham chiếu Java API Phần 2 Tài liệu tham chiếu Java APIPhần 2: Sử dụng JavaTOC doclet để sinh cấu trúc tham chiếu Eclipse JavadocAPIMariana Alupului, Phát triển Thông tin, Rational software, IBMTóm tắt: 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ácnhau để 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 nhanhTrong phần 1 của loạt bài này, Tài liệu tham chiếu Java API được tổ chứctrong 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 docletmà tôi đã phát triển để tạo ra hệ trợ giúp trình bổ sung Eclipse. Công cụ JavaTOCdoclet 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ếpcậ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).Về đầu trangCấu trúc tham chiếu Eclipse Javadoc API được tạo ra với JavaTOC docletCá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ăngcao, 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 JavaAPI, định hướng mục lục và cấu trúc trình bổ sung. Hoặc bạn có thể chỉ chạyJavaTOC 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ìnhviên đã tạo ra và chuyển cho bạn.Luồng công việcVới mỗi trình bổ sung mà bạn muốn đóng góp cho hệ trợ giúp Eclipse (phần thamchiế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 đangsử dụng. Nếu bạn chưa từng làm việc với Ant thì hãy xem ở trang thông tinJakarta, 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âydự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 JavaTOCdoclet 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ệnhCá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 cungcấ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ậptrì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_06injavadoc.exe) GHI CHÚ: thông thường Javadoc sẽ có một đường dẫn có dạng o C:Program FilesJavajdk1.5.0_06in. 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 o 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 o 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ử o 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: DITA-OT1.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. 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:docletinTOCNavDoclet.jarVí dụ 2. các tùy chọn-source ...