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

Chia sẻ: Nguyen Nhi | Ngày: | Loại File: PDF | Số trang:25

Thêm vào BST

Báo xấu

124
lượt xem 21
download

Download Vui lòng tải xuống để xem tài liệu đầy đủ

Tài liệu tham chiếu Java API Tài liệu tham chiếu Java API được tổ chức trong trợ giúp Eclipse như thế nào Mariana Alupului, Phát triển Thông tin, Rational software, IBM Tóm tắt: Bài viết này mô tả các cách tiếp cận khác nhau để tạo ra tài liệu tham chiếu giao diện lập trình ứng dụng Java dễ sử dụng và có thể tìm kiếm được. Các kiến thức cơ sở Cải thiện tính khả dụng của tài liệu sản phẩm là chìa khóa thành công của nhiều dự án. Sự thành công này có thể được quy trực...

Chủ đề:

Bình luận(0) Đăng nhập để gửi bình luận!

Lưu

Nội dung Text: Tài liệu tham chiếu Java API

Tài liệu tham chiếu Java API Tài liệu tham chiếu Java API được tổ chức trong trợ giúp Eclipse như thế nào Mariana Alupului, Phát triển Thông tin, Rational software, IBM Tóm tắt: Bài viết này mô tả các cách tiếp cận khác nhau để tạo ra tài liệu tham chiếu giao diện lập trình ứng dụng Java dễ sử dụng và có thể tìm kiếm được. Các kiến thức cơ sở Cải thiện tính khả dụng của tài liệu sản phẩm là chìa khóa thành công của nhiều dự án. Sự thành công này có thể được quy trực tiếp cho nỗ lực tạo ra và viết tài liệu tốt. Bài viết này giả sử rằng bạn đã quen thuộc với phần mềm Java, cấu trúc tài liệu tham chiếu Java API, việc sinh ra Javadoc và bây giờ bạn muốn biết thêm về việc làm thế nào để tạo ra được tài liệu tham chiếu Java API nâng cao. Với những người bắt đầu thì bạn phải tự làm quen với: Javadoc, một công cụ mã nguồn mở được Sun Microsystems tạo ra. Để biết • thêm chi tiết, hãy đọc java.sun.com/j2se/javadoc. JavaHelp, là một tập trợ giúp, có khả năng đánh số và tìm kiếm. Để có thêm • thông tin, hãy xem tại java.sun.com/products/javahelp. Các công cụ chính thức từ JavaHelp. Để có thêm thông tin, hãy tham khảo • danh sách ở java.sun.com/products/javahelp/industry.html. Các quy ước mã hóa Java chuẩn. Xem chi tiết tại • java.sun.com/docs/codeconv và một trang tham khảo nhanh.
Các quy ước Javadoc. Xem chi tiết tại • java.sun.com/j2se/javadoc/writingdoccomments. Về đầu trang Xây dựng tài liệu tham chiếu Java API dễ sử dụng và có thể tìm kiếm được Bài viết này mô tả các cách tiếp cận khác nhau để tạo ra tài liệu tham chiếu giao diện lập trình ứng dụng Java dễ sử dụng và có thể tìm kiếm được. Các cách tiếp cận được mô tả ở đây là giải pháp chuẩn Javadoc và sử dụng JavaTOC doclet tôi đã phát triển để tạo ra hệ thống trợ giúp trình bổ sung Eclipse. JavaTOC doclet tạo ra mục lục (TOC) cho tài liệu tham chiếu Javadoc API, mục lục này giúp người dùng có thể dễ dàng tìm một lớp, giao diện hoặc phương thức nào đó trong tài liệu tham chiếu API. Tài liệu tham chiếu Javadoc API cần phải vừa duyệt được và vừa tìm kiếm được. Javadoc chuẩn không cung cấp đầy đủ khả năng này. Một API được làm tài liệu đầy đủ có thể phục vụ cho nhiều mục đích, nhưng lý do quan trọng nhất là cho phép người dùng hiểu một cách đầy đủ và tìm kiếm toàn diện các chức năng API có sẵn của mình. Nếu không được làm tài liệu một cách đúng đắn hoặc không thể tìm kiếm được thì thậm chí ngay chính tác giả cũng có thể không hiểu nổi mã nguồn mà mình đã viết ra. Giải pháp là tập thói quen làm tài liệu cho mã nguồn và tạo cấu trúc có thể tìm kiếm được (mục lục định hướng) cho các tham chiếu Java API. JavaTOC doclet giải quyết vấn đề này bằng cách tạo ra cấu trúc có thể tìm kiếm được cho các tham chiếu. Việc tìm kiếm và duyệt giả sử rằng thông tin đã được sắp xếp theo mức độ liên quan cho một truy vấn cụ thể, tạo ra kết quả là một số lượng bất kì các trình tự đặc
biệt. Ví dụ, trong Javadoc chuẩn, một phép tìm kiếm phần mô tả của một phương thức cụ thể trong thông tin API trả lại kết quả là phần mô tả của toàn bộ lớp. Về đầu trang Các cách tiếp cận được cân nhắc Giải pháp là tập thói quen làm tài liệu cho mã nguồn. Nếu không được làm tài liệu một cách đúng đắn thì thậm chí ngay chính tác giả cũng có thể không hiểu nổi mã nguồn mà mình đã viết ra. Có khá ít các công cụ để tạo ra tài liệu tham chiếu Java API. Gợi ý hiện tại của tôi là dùng kết hợp JavaTOC doclet và Javadoc hoặc đặc tả DITA API. Javadoc là một công cụ do Sun sở hữu, công cụ này lấy ra các ghi chú của • lập trình viên từ mã nguồn Java và xuất chúng sang HTML. Công cụ Javadoc tạo ra cấu trúc cơ sở của tài liệu tham chiếu Java API. Kết quả là tài liệu Javadoc HTML API cho một tập các gói và các lớp. JavaTOC doclet tạo ra mục lục định hướng và khả năng tìm kiếm cho tài • liệu tham chiếu Java API. Đội đặc tả IBM DITA API đã phát triển gói các kiểu chủ đề DITA để tạo ra các tệp tài liệu Java API và bản kê định hướng cho các tham chiếu sẽ có trong hệ thống trợ giúp Eclipse. Các ví dụ sau đây (Ví dụ tham chiếu API không có mục lục định hướng và Ví dụ tham chiếu API có mục lục định hướng) sử dụng mã nguồn Java từ Bộ dụng cụ (Toolkit) mở DITA. Bộ dụng cụ mở DITA phiên bản mới hơn hoặc bằng 1.0.2 đưa ra giao diện dòng lệnh như là một sự lựa chọn khác để giúp cho những người
dùng có ít kiến thức về Ant có thể sử dụng bộ công cụ được dễ dàng. Sau khi tải xuống tệp zip, bạn có thể thấy mã nguồn được sử dụng cho ví dụ của bài viết này trong thư mục DITA-OT1.2_src\DITA-OT1.2-src\src. Về đầu trang Về Javadoc và JavaTOC doclet Sự khác biệt lớn nhất giữa trợ giúp Javadoc chuẩn và trợ giúp Eclipse Javadoc là việc cung cấp mục lục định hướng. Trợ giúp Javadoc chuẩn cung cấp thêm một số khung để giúp bạn duyệt các gói và các lớp. Trợ giúp Eclipse Javadoc đã được tùy biến chứa các tệp định hướng XML kiểu Eclipse chứ không phải các khung HTML được cung cấp thêm đó. Các tệp định hướng XML kiểu Eclipse tạo ra mục lục định hướng, mục lục này cho phép người dùng tìm một gói, lớp hoặc giao diện cụ thể. Giải pháp tham chiếu Eclipse Java API tùy biến cung cấp bảng kê định hướng cho các tài liệu sẽ có trong hệ thống trợ giúp Eclipse. Toàn bộ nền Eclipse được phát triển xoay quanh ý tưởng về các trình bổ sung. Nếu bạn muốn đưa tài liệu trợ giúp của mình vào nền Eclipse, thì bạn phải phát triển một trình bổ sung trợ giúp mới. Trình bổ sung đó bao gồm các tệp ảnh và tệp HTML, tệp mục lục ở dạng XML và tệp bảng kê. JavaTOC doclet tự động sinh ra toàn bộ cấu trúc trình bổ sung Eclipse, cấu trúc này chứa tệp mục lục định hướng XML được lấy ra trực tiếp từ mã nguồn Java. JavaTOC doclet là chương trình được tùy biến, chương trình này cũng làm việc với công cụ Javadoc. Doclet này tăng cường độ linh hoạt, cho phép bạn tạo ra mục lục định hướng phía trên các tệp tài liệu Javadoc.
JavaTOC doclet được tích hợp với công cụ DITAdoclet cho đặc tả IBM DITA API, đặc tả này được phát triển để sinh ra các tệp Java DITA (XML) API phục vụ cho việc tạo tài liệu và sinh các tham chiếu Java API. Giải pháp này cũng bao gồm các bảng kê định hướng cho tài liệu tham chiếu Java API, tài liệu này sẽ có trong hệ trợ giúp Eclipse. Về đầu trang Cấu trúc tham chiếu Eclipse Javadoc API được tạo ra với công cụ Javadoc chuẩn Để truy cập trợ giúp trực tuyến Javadoc chuẩn trong Eclipse, bạn có thể chọn Help > Help Contents trên thanh thực đơn. Việc này sẽ mở trợ giúp trực tuyến trong chính trình duyệt của nó. Trong khung ở bên trái, có khung nhìn dạng thẻ cho các liên kết mục lục, tìm kiếm và trợ giúp theo ngữ cảnh. Ví dụ dưới đây (Hình 1) thể hiện một cấu trúc tham chiếu Javadoc API chuẩn, được sinh ra chỉ bằng cách sử dụng công cụ Javadoc chuẩn trong môi trường Eclipse.
Hình 1. Cấu trúc các tham chiếu Javadoc API Phần đuôi mở rộng của org.eclipse.help.toc nhận biết đây là một trình bổ sung vào hệ thống trợ giúp. Ví dụ 1. plug-in.xml
< toc file="doclet.toc.xml" primary="true"/> Ví dụ 2. MANIFEST.MF Manifest-Version: 1.0 Bundle-ManifestVersion: 2 Bundle-Name: Doc Plug-in Bundle-SymbolicName: org.dita.dost.doc; singleton:=true
Bundle-Version: 1.0.0 Bundle-Activator: org.dita.dost.doc.DocPlugin Bundle-Localization: plugin Require-Bundle: org.eclipse.ui, org.eclipse.core.runtime Eclipse-AutoStart: true hoặc Ví dụ 3. plug-in.xml
id = "org.dita.dost.user.doc" version = "7.0.1.0" provider-name = "%Plugin.providerName"> < toc file="doclet.toc.xml" primary="true"/> Đổi tên, id, phiên bản, và tên nhà cung cấp của trình bổ sung sang các giá trị phù hợp với dự án của bạn. Ví dụ 4. plugin.properties # NLS_MESSAGEFORMAT_VAR #
========================================================== ==================== # Trợ giúp trực tuyến - Hướng dẫn dịch: phần sẽ được dịch # ========================================================== =================== Plugin.name = Building DITA output Plugin.providerName = IBM Tệp doclet.toc.xml được coi là mục lục của trình bổ sung này; tệp này sẽ cung cấp dữ liệu cho thông tin có tính phân cấp trong khung ở bên trái của cửa sổ trợ giúp Eclipse. Một tệp đơn giản có nội dung kiểu như được hiển thị ở ví dụ 2. Ví dụ 5. doclet.toc.xml
Trong đó href = "index.html" là liên kết tới các tham chiếu javadoc api đã được tạo ra. Nếu bạn muốn các tham chiếu đó có trong khung ở bên phải để mở các tài liệu mà không cần đến các khung HTML thì liên kết sẽ có dạng href="overview- summary.html". Về đầu trang Cấu tạo thanh định hướng Javadoc chuẩn Thanh định hướng Javadoc chuẩn không cho phép người dùng tìm kiếm một gói, lớp hay phương thức cụ thể. Đây là cách định hướng thẻ Javadoc được cấu tạo và mô tả bởi SUN Javadoc-- Hình 2. Hình 2. Định hướng thẻ Javadoc Để tạo ra một tệp chú giải gói, bạn phải đặt tên cho nó là package.html và đặt tệp đó trong thư mục gói trong cây nguồn, cùng với các tệp .java. Javadoc sẽ tự động tìm tên tệp này trong thư mục đó. Chú ý rằng tên tệp này là giống hệt nhau đối với tất cả các gói.
Nội dung của tệp chú giải gói là một chú giải tài liệu lớn, được viết dưới dạng HTML, giống như tất cả các chú giải khác nhưng có một ngoại lệ: Chú giải tài liệu không được chứa các ngăn cách chú giải /** và */ hoặc các dấu hoa thị ở đầu. Khi viết chú giải, bạn nên tóm tắt về gói ở câu đầu tiên và không đặt tiêu đề hoặc bất cứ văn bản nào ở giữa và câu đầu tiên. Bạn có thể đưa vào đó các thẻ gói; giống như mọi chú giải tài liệu, tất cả các thẻ ngoại trừ {@link} phải xuất hiện sau phần miêu tả. Nếu bạn thêm một thẻ @see vào một tệp chú giải gói thì thẻ đó phải có tên với đầy đủ các điều kiện. SUN Javadoc sẽ sinh ra đầu ra bắt nguồn từ bốn kiểu khác nhau các tệp "nguồn": Các tệp nguồn ngôn ngữ Java (.java), các tệp chú giải gói, các tệp chú giải tổng quan và các tệp chưa xử lý hỗn hợp. Tổng quan Trang tổng quan là trang đầu của tài liệu API này, trang này cung cấp một danh sách tất cả các gói cùng với bản tóm tắt cho mỗi gói. Trang này cũng có thể chứa mô tả toàn diện của tập các gói. LỜI BÌNH: Đừng quên viết Javadoc cấp độ gói trong một tệp có tên là • Overview.html. Nên đặt tệp này ở thư mục gốc, nơi có các tệp mã. Javadoc có khả năng lấy tệp đó và sử dụng nội dung của nó. . Gói (package)
Mỗi gói có một trang, trang này chứa danh sách các lớp và các giao diện của nó cùng với bản tóm tắt cho mỗi thành phần. Trang này có thể chứa năm loại: giao diện, lớp, ngoại lệ, lỗi, và hằng số. LỜI BÌNH: Đừng quên viết Javadoc cấp độ gói trong tệp có tên là package.html. • Nên đặt tệp này vào thư mục, nơi mà có các tệp mã cho gói đó. Javadoc có khả năng lấy tệp đó và sử dụng nội dung của nó. . Lớp/Giao diện (Class/Interface) Mỗi lớp, giao diện, lớp bên trong, giao diện bên trong có một trang riêng của nó. Mỗi trang này có 3 phần bao gồm một mô tả lớp/giao diện, các bảng tóm tắt và các mô tả thành viên chi tiết: Mỗi mục tóm tắt chứa câu đầu tiên của phần mô tả chi tiết cho phần đó. Các mục tóm tắt được sắp xếp theo bảng chữ cái, trong khi các mô tả chi tiết thì theo thứ tự chúng xuất hiện trong mã nguồn. Việc này bảo tồn việc phân nhóm mang tính lôgic đã được lập trình viên lập ra. Sử dụng (Use) Mỗi gói, lớp và giao diện đã được làm tài liệu có trang sử dụng riêng của mình. Trang này miêu tả các gói, lớp, phương thức, hàm thành viên của lớp, trường nào sử dụng bất cứ phần nào của lớp hoặc gói đã cho. Cây - Phân bậc theo lớp (Tree) Có một trang cây (phân bậc theo lớp) cho tất cả các gói, cùng với một phân bậc cho mỗi gói. Mỗi trang phân bậc chứa một danh sách các lớp và một danh sách các giao diện.
Nên tránh (Deprecated) Trang API nên tránh liệt kê toàn bộ các API được khuyên là nên tránh. Người ta khuyên không nên dùng các API nên tránh, thường là do các quá trình cải tiến tạo ra, và họ cũng thường cung cấp các API thay thế. Các API nên tránh có thể bị xóa trong các lần thực thi trong tương lai. Chỉ mục (Index ) Chỉ mục chứa một danh sách theo thứ tự bảng chữ cái của tất cả các lớp, các giao diện, các hàm thành viên của lớp, các phương thức và các trường. Trước/Kế tiếp (Prev/Next) Các liên kết này đưa bạn tới lớp, giao diện, gói hoặc trang có liên quan ở trước hay tiếp sau. Khung/ Không khung (Frames/No Frames) Các liên kết này sẽ cho hiện hoặc ẩn các khung HTML. Tất cả các trang sẽ có hoặc không có khung. Về đầu trang Sử dụng JavaTOC doclet để sinh ra cấu trúc tham chiếu Eclipse Javadoc API Cách tiếp cận thông tin có cấu trúc như trong XML sử dụng Eclipse JavaTOC doclet và kiểu trợ giúp Javadoc thỏa mãn các yêu cầu của tài liệu tham chiếu Java API có thể duyệt và tìm kiếm được.
Để kích hoạt định hướng trong một trình bổ sung trợ giúp Eclipse, người phát triển thông tin phải cung cấp mục lục (TOC) được viết như một tài liệu XML. Tài liệu này được cung cấp với một chỉ mục có thể xếp gọn lại được ở bên trái và tài liệu HTML ở bên phải. Có thể sử dụng Javadoc hoặc đặc tả IBM DITA Java API để tạo ra các tệp HTML. Bằng cách sử dụng JavaTOC doclet, bạn có thể tạo ra mục lục bằng tay hoặc tự động. JavaTOC doclet sinh ra cho bạn cấu trúc mục lục các tham chiếu Java API, cấu trúc này liệt kê các gói và các lớp, các giao diện chứa trong đó. Để tạo ra các tệp HTML tham chiếu API, bạn có thể chạy công cụ Javadoc hoặc sử dụng giải pháp đặc tả IBM DITA API để ủy quyền và sinh ra các tệp HTML tham chiếu Java API -- Hình 3. Hình 3. Bộ soạn thảo HTML—Kit
Nếu bạn sử dụng JavaTOC doclet, tài liệu tham chiếu API vừa có thể duyệt được và vừa có thể tìm kiếm được. Khả năng có thể tìm kiếm được là do cách tiếp cận thông tin có cấu trúc (XML) đã được sử dụng. Một trong những hiệu ứng phụ có lợi của việc sử dụng XML để sinh ra cấu trúc của tài liệu tham chiếu API là nội dung sẽ được đánh chỉ mục một cách tự động, phục vụ cho việc tìm kiếm; nếu bạn dùng giải pháp Javadoc chuẩn để sinh ra nội dung, thì ngầm định là nó sẽ không được đánh số để phục vụ cho việc tìm kiếm. Về đầu trang Các tệp cần thiết cho cấu trúc tham chiếu Eclipse Java API và việc sinh mục lục Các liệt kê dưới đây cho ta các ví dụ về các tệp XML mục lục được sử dụng để sinh cấu trúc mục lục định hướng tham chiếu Java API ở trên. Bằng cách sử dụng JavaTOC doclet, các tệp có thể được sinh ra bằng tay hoặc tự động. Xem phần tải xuống dưới đây để tải về các ví dụ mục lục XML tham chiếu Java API cho Eclipse. Liệt kê dưới đây đưa ra ví dụ của một trình bổ sung tham chiếu Eclipse Java API, trình bổ sung này tham chiếu tới một tệp XML mục lục. Ví dụ 6. plug-in.xml
Liệt kê dưới đây đưa ra cùng ví dụ về một trình bổ sung tham chiếu Eclipse Java API, trình bổ sung này tham chiếu đến hơn một tệp XML mục lục dựa vào cấu trúc gói Java. Khi quan sát tài liệu, sẽ không có sự khác biệt nào giữa việc sử dụng cách tiếp cận một tệp XML mục lục hay nhiều tệp XML mục lục. Ví dụ 7. plug-in.xml
Bạn có thể sử dụng các phần tử navref và anchor, thêm thuộc tính anchorref của phần tử ánh xạ, để tạo ra các điểm tích hợp trong đầu ra Eclipse, nơi mà tệp định hướng được lấy vào hoặc tự gắn vào tại thời gian chạy. Để có thêm thông tin về việc ủy quyền các tệp định hướng Eclipse, hãy xem các tài nguyên Eclipse
Ví dụ 8. doclet.toc.xml