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

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 <?xml version="1.0" encoding="UTF-8"?> <?eclipse version="1.0"?> <plugin> <extension point="org.eclipse.help.toc"> < toc file="doclet.toc.xml" primary="true"/> </extension> </plugin> 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 <?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"/> </extension> </plugin> Đổ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 <?xml version="1.0" encoding="UTF-8"?> <?NLS TYPE="org.eclipse.help.toc"?> <toc label="Building DITA output"> [...]... đặc tả Java DITA API và cách sử dụng nó Mục lục • Cấu trúc tài liệu tham chiếu Java API • 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 • Các cách tiếp cận được cân nhắc • Về Javadoc và JavaTOC doclet • Cấu trúc tham chiếu Eclipse Javadoc API được tạo ra với công cụ Javadoc chuẩn • Cấu tạo thanh định hướng Javadoc chuẩn • Sử dụng JavaTOC doclet để sinh ra cấu trúc tham chiếu. .. 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... đượ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... tương lai, Cấu trúc tham chiếu Eclipse Java API được sinh ra với JavaTOC doclet sẽ mô tả quy trình sử dụng JavaTOC doclet và hệ thống trợ giúp trình bổ sung Eclipse để tạo ra một cách tự động tài liệu tham chiếu Java API có thể tìm kiếm được (mục lục định hướng) Trong các bài viết sắp tới của loạt bài này, chúng tôi cũng sẽ khai thác sâu hơn về việc ủy quyền và công nghệ sinh tài liệu API cũng như một... 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. .. (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à... 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="overviewsummary.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... 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... point="org.eclipse.help.toc"> 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 . 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. 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. 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,