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...
Nội dung trích xuất từ tài liệu:
Tài liệu tham chiếu Java API Tài liệu tham chiếu Java APITài liệu tham chiếu Java API được tổ chức trong trợ giúp Eclipse như thế nàoMariana Alupului, Phát triển Thông tin, Rational software, IBMTó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 thamchiế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ệutố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ệutham chiếu Java API, việc sinh ra Javadoc và bây giờ bạn muốn biết thêm về việclà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 trangXây dựng tài liệu tham chiếu Java API dễ sử dụng và có thể tìm kiếm đượcBà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 giaodiệ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ếpcậ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ạora mục lục (TOC) cho tài liệu tham chiếu Javadoc API, mục lục này giúp ngườidù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ệutham 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à chophé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 APIcó 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 JavaAPI. JavaTOC doclet giải quyết vấn đề này bằng cách tạo ra cấu trúc có thể tìmkiế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ênquan 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ự đặcbiệt. Ví dụ, trong Javadoc chuẩn, một phép tìm kiếm phần mô tả của một phươngthứ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 trangCác cách tiếp cận được cân nhắcGiả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ệumộ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ôilà 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ụngcụ (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ườidù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ảixuố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àytrong thư mục DITA-OT1.2_srcDITA-OT1.2-srcsrc.Về đầu trangVề Javadoc và JavaTOC docletSự 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 đ ...