Javadoc là công cụ mạnh mẽ, dùng để sinh tài liệu API từ mã nguồn Java. Javadoc được đóng gói và phân phối trong bộ JDK, rất thuận tiện để lập trình viên tạo tài liệu API nhanh chóng cho dự án của mình. Javadoc không chỉ được các công cụ IDE như Eclipse, Netbeans gọi trực tiếp từ giao diện mà còn có thể tích hợp sử dụng với Maven – là công cụ quản lý và build dự án Java phổ biến nhất hiện này. Bài viết này giới thiệu về cú pháp Javadoc và cách thức sử dụng Javadoc với Maven dễ dàng thông qua plugin.

Giới thiệu về Javadoc

Javadoc là gì?

Javadoc là bộ công cụ sinh tài liệu nằm trong bộ công cụ phát triển Java (JDK) của Oracle để tạo ra tài liệu theo định dạng HTML từ mã nguồn Java. Định dạng HTML tạo thuận lợi để từ một tài liệu có thể tham chiếu đến các tài liệu khác có liên quan. Javadoc được dùng để tạo ra tài liệu tham khảo hỗ trợ cho các lập trình viên.

Một số môi trường phát triển tích hợp (Intergrated Development Enviroment - IDE) như Netbeans, Eclipse tự động tạo ra Javadoc ở định dạng HTML.

Để tạo ra công cụ Javadoc, các nhà phát triển (trước đây là SUN) đã định nghĩa Doclet API là cấu trúc interface, class mà chương trình chuyển đổi tài liệu cần cài đặt. Chương trình chuyển đổi tài liệu được gọi là Doclet, là một chương trình viết bằng ngôn ngữ Java cài đặt Doclet API để xác định nội dung từ phần chú thích tài liệu trong mã nguồn Java và định dạng các nội dung này thành tài liệu HTML. Mặc định, công cụ Javadoc cung cấp một chương trình chuyển đổi tài liệu cài sẵn - gọi là Doclet tiêu chuẩn - để tạo tài liệu API theo định dạng HTML. Tuy nhiên bạn có thể tạo Doclet của riêng mình để tùy chỉnh các tài liệu sinh ra bởi Javadoc theo định dạng như mong muốn.

Cú pháp Javadoc

Một chú thích tài liệu Javadoc được đặt trong cặp dấu /** ...*/.

Chú thích tài liệu Javadoc nằm trước khai báo một lớp đối tượng hoặc phương thức. Bên trong một chú thích tài liệu bao gồm hai phần, phần thứ nhất mô tả bằng lời về chức năng của lớp đối tượng, phương thức; phần thứ hai là các thẻ @param, @return, @see,...

Ví dụ:

/**
 * Returns an Image object that can then be painted on the screen.  
 *   The url argument must specify an absolute {@link URL}. The name 
 *   argument is a specifier that is relative to the url argument.  
 *   <p>  
 *   This method always returns immediately, whether or not the  
 *   image exists. When this applet attempts to draw the image on  
 *   the screen, the data will be loaded. The graphics primitives  
 *   that draw the image will incrementally paint on the screen. 
 *
 *   @param   url  an absolute URL giving the base location of the image  
 *   @param   name the location of the image, relative to the url argument  
 *
 *   @return  the image at the specified URL
 *
 *   @see     Image 
 */
 
 public Image getImage(URL url, String name) {
        try {
            return getImage(new URL(url, name));
        } 
        catch (MalformedURLException e) {
            return null;
        }
}

Kết quả chạy Javadoc được hiển thị dưới đây:

Với các mô tả cho class, phương thức thì nên mô tả ngắn gọn ý nghĩa, mục đích của từng class, phương thức; lưu ý chỉ thực sự thêm một liên kết {@link} đến một mục API khác khi người dùng muốn click vào đó để biết thêm thông tin.

Với các Tag Comments, bao gồm các thẻ theo thứ tự sau:

• @author: xác định tác giả thực hiện các classes và interfaces.

• @version: có dạng %I%, %G%, với %I% được tăng lên khi chỉnh sửa tập tin, mặc định khi tạo là 1.1 sau khi chỉnh sửa thì tăng lên 1.2, %G% với định dạng mm/dd/yy, dùng khi chú thích cho các classes và interfaces.

• @param: mô tả các tham số, dùng khi chú thích cho các methods và constructors.

• @return: mô tả dữ liệu hay giá trị trả về, dùng khi chú thích cho methods.

• @exception (@throws): khai báo các ngoại lệ mà phương thức có thể ném ra.

• @see: khai báo liên kết đến tài liệu khác để xem thêm.

• @since: cho biết lớp đối tượng/phương thức bắt đầu từ phiên bản nào.

• @serial (@serialField hoặc @serialData).

• @deprecated: thông báo class hoặc phương thức đã lỗi thời và hướng dẫn cách dùng khác để thay thế.

Biên dịch Javadoc

Sau khi thực hiện viết javadoc trong các class của 1 project thì bạn có thể biên dịch javadoc để xem kết quả trả về là các trang html.

Ví dụ sau đây minh họa cho các bước thực hiện viết javadoc với Netbeans 7.4.

Project JavaDocUsage được thiết kế có 2 class là Person và Car nằm trong package javadocusage.beans.

Khi viết xong Javadoc, để biên dịch Javadoc thành các trang html, bạn chọn Project đang thực hiện, click chuột phải -> Generate Javadoc như hình dưới.

Kết quả sau khi biên dịch, tài liệu API do Javadoc sinh ra được lưu trong thư mục project của bạn.

Bạn có thể sử dụng command line để chạy Javadoc để tạo ra tài liệu API tương tự như trên:

javadoc -version -author -d ^
D:\NetBeansProjects\JavaDocUsage\src\javadocusage\beans *.java

Kết quả sau khi tạo ra Javadoc:

Sử dụng Javadoc với Maven

Các bước thực hiện viết Javadoc trong các class tương tự như trên. Ở đây chỉ hướng dẫn cách biên dịch Javadoc với Maven.

Đầu tiên bạn tải Maven về máy và thiết lập môi trường để chạy Maven.

Sau đó bạn tạo một project Maven trong Netbeans rồi thực hiện việc tạo tài liệu Javadoc cho project Maven.

Ví dụ minh họa

Sử dụng lại ví dụ ở trên, tạo project Maven với tên gọi example-javadoc-with-maven. Sau khi thực hiện biên dịch chú thích tài liệu Javadoc cho hai class Car và Person ta thực hiện các bước sau:

• Tại thư mục Project Files: chọn file pom.xml để khai báo Maven plugins.

• Sau đó, nhấn chuột phải vào project chọn Custom -> Goals.

• Tại đây, bạn điền plugin của javadoc vào và nhấn OK.

Maven Javadoc Plugin có 14 goals nhưng ta chỉ sử dụng một số goals phổ biến như sau:

• javadoc:javadoc

• javadoc:test-javadoc

• javadoc:jar

• javadoc:test-jar

Sau khi click vào Ok, Maven Javadoc Plugin sẽ thực hiện biên dịch và tạo tài liệu API. Nếu không gặp lỗi gì, quá trình biên dịch kết thúc với thông báo “BUILD SUCCESS”.

Khai báo maven plugins

Khai báo maven plugins được quy định nằm trong file pom.xml của project.

<dependency>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.10.1</version>
</dependency>

Kết quả chạy ví dụ

Sau khi biên dịch, Maven Javadoc Plugin sẽ chạy và sinh ra tài liệu API lưu trong thư mục target/site/apidocs bên trong thư mục gốc project của bạn:

Kết luận

Bài viết giới thiệu về cách thức sử dụng Javadoc để tạo các tài liệu chú thích cho dự án của mình đặc biệt là dự án sử dụng Maven. Đây là công cụ cần thiết đối với những dự án lớn để người lập trình có thể tạo và chia sẻ tài liệu API cho nhau. Các bạn có thể tải mã nguồn của ví dụ dùng Javadoc với Maven để chạy thử.