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à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

<plugin>

<extension point="org.eclipse.help.toc"> < toc file="doclet.toc.xml" primary="true"/> </extension>

Bundle-Version: 1.0.0

Bundle-Activator: org.dita.dost.doc.DocPlugin Bundle-Localization: plugin

<plugin

name = "%Plugin.name"

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

<topic label="API References" href="index.html"/>

</toc>

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 Hình 2

Javadoc 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ớ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

Ví dụ 7 plug-in.xml

<?xml version="1.0" encoding="UTF-8"?> <?eclipse version="1.0"?>

Ví dụ 8 doclet.toc.xml

<?xml version="1.0" encoding="UTF-8"?>

<?NLS TYPE="org.eclipse.help.toc"?>

<toc label="Building DITA output">

<topic label="Overview" summary.html">

<link toc="org.dita.dost.exception.toc.xml"/> <link toc="org.dita.dost.index.toc.xml"/> <link toc="org.dita.dost.invoker.toc.xml"/> <link toc="org.dita.dost.log.toc.xml"/> <link toc="org.dita.dost.module.toc.xml"/> <link toc="org.dita.dost.pipeline.toc.xml"/> <link toc="org.dita.dost.platform.toc.xml"/>

<topic label="org.dita.dost.index Package"

Mã nguồn không được tạo tài liệu sẽ khó hoặc không thể hiểu, không thể sử dụng được, và không thể quản lý được JavaToc doclet là một công cụ đáng giá Tôi thực sự hy vọng rằng bài viết này sẽ giúp bạn tìm thấy một số điểm thú vị trong việc kết hợp JavaToc doclet vào dự án của mình

Về đầu trang

Ghi chú

"Sự đơn giản là linh hồn của hiệu quả" — Austin Freeman

"Ngày nay chúng ta sống trong thời đại của chuyên môn hóa Lượng thông tin có trong môi trường kiến thức lớn tới mức để hiểu và làm việc với nó, mỗi người phải trở thành một chuyên gia Vì ngày càng có nhiều các kiến thức quan trọng, nên việc học tập cũng cần đa dạng hơn và chúng ta cũng cần có nhiều chuyên gia hơn."

Thông tin được cung cấp trong tài liệu này chưa từng được thực hiện bất cứ kiểm tra IBM chính thức 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 ý

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

Về đầu trang