Ngôn ngữ Java hỗ trợ 3 kiểu comment sau:
| Comment | Miêu tả |
|---|---|
| /* text */ | Trình biên dịch bỏ qua mọi thứ từ /* tới */. |
| // text | Trình biên dịch bỏ qua mọi thứ từ // tới cuối dòng. |
| /** documentation */ | Đây là một Documentation Comment và nói chung nó được gọi là doc comment. Công cụ JDK javadoc sử dụng doc comment khi tự động chuẩn bị documentation đã tạo. |
Javadoc là gì?
Javadoc là một công cụ đi với JDK và nó được sử dụng để tạo Java code documentation trong định dạng HTML từ Java source code mà đã yêu cầu Documentation trong một định dạng đã định trước.
Trong ví dụ đơn giản sau, phần màu đỏ của code biểu diễn Java comment:
/** * Chuong trinh HelloWorld don gian sau trien khai mot ung dung ma * hien thi "Hello World!" toi standard output. * * @author Zara Ali * @version 1.0 * @since 2014-03-31 */ public class HelloWorld { public static void main(String[] args) { /* In dong chu Hello, World! tren standard output. System.out.println("Hello World!"); } }
Bạn có thể bao gồm các thẻ HTML được yêu cầu bên trong phần mô tả, ví dụ sau sử dụng <h1>....</h1> cho heading và <p> được sử dụng để tạo các đoạn văn:
/** * <h1>Hello, World!</h1> * Chuong trinh HelloWorld don gian sau trien khai mot ung dung ma * hien thi "Hello World!" toi standard output. * <p> * Viec cung cap comment thich hop trong chuong trinh giup no tro nen * than thien voi nguoi dung hon. * * * @author Zara Ali * @version 1.0 * @since 2014-03-31 */ public class HelloWorld { public static void main(String[] args) { /* In dong chu Hello, World! tren standard output. System.out.println("Hello World!"); } }
Các thẻ javadoc trong Java
Công cụ javadoc thừa nhận các thẻ sau:
| Thẻ | Miêu tả | Cú pháp |
|---|---|---|
| @author | Thêm author của một lớp | @author name-text |
| {@code} | Hiển thị text trong code font mà không thông dịch text như là các thẻ HTML markup hoặc javadoc được lồng. | {@code text} |
| {@docRoot} | Biểu diễn relative path tới thư mục root của tài liệu từ các trang được tạo | {@docRoot} |
| @deprecated | Thêm một comment chỉ dẫn rằng API này không còn được sử dụng nữa | @deprecated deprecated-text |
| @exception | Thêm một Throws subheading tới documentation được tạo, với tên lớp và text mô tả | @exception class-name Miêu tả |
| {@inheritDoc} | Kế thừa một comment từ lớp có thể kế thừa gần nhất hoặc interface có thể triển khai | Kế thừa một comment từ một lớp cha trung gian. |
| {@link} | Chèn một in-line link với nhãn text có thể nhìn thấy mà chỉ tới Documentation cho package, lớp hoặc tên member đã xác định của một lớp tham chiếu | {@link package.class#member label} |
| {@linkplain} | Giống {@link}, ngoại trừ label của link được hiển thị ở dạng plain text thay vì code font. | {@linkplain package.class#member label} |
| @param | Thêm một tham số với parameter-name đã xác định được theo sau bởi description đã xác định tới khu vực "Parameters". | @param parameter-name Miêu tả |
| @return | Thêm một khu vực "Returns" với Miêu tả | @return Miêu tả |
| @see | Thêm một "See Also" heading với một link hoặc text mà chỉ tới reference | @see reference |
| @serial | Được sử dụng trong doc comment cho một trường có thể xếp thứ tự. | @serial field-description | include | exclude |
| @serialData | Thu thập thông tin dữ liệu được viết bởi phương thức writeObject( ) hoặc writeExternal( ) | @serialData data-Miêu tả |
| @serialField | Thu thập thông tin một thành phần ObjectStreamField | @serialField field-name field-type field-Miêu tả |
| @since | Thêm một "Since" heading với since-text đã xác định tới Documentation đã tạo | @since release |
| @throws | Thẻ @throws và @exception là như nhau | @throws class-name Miêu tả |
| {@value} | Khi {@value} được sử dụng trong doc comment của một trường static, nó hiển thị giá trị của hằng số đó | {@value package.class#field} |
| @version | Thêm một "Version" subheading với version-text đã xác định tới Documentation đã tạo khi tùy chọn -version được sử dụng | @version version-text |
Ví dụ:
Chương trình sau sử dụng một số thẻ quan trọng có sẵn cho Documentation comment. Bạn có thể sử dụng các thẻ khác tùy theo yêu cầu của bạn.
Documentation về lớp AddNum sẽ được tạo trong HTML file là AddNum.html nhưng cùng thời điểm đó một master file với tên là index.html cũng sẽ được tạo.
import java.io.*;/** * <h1>Add Two Numbers!</h1> * Chuong trinh AddNum trien khai mot ung dung ma * cong hai so integer da cho va in chung * the output on the screen. * <p> * <b>Note:</b> Viec cung cap comment thich hop trong chuong trinh giup no tro nen * than thien voi nguoi dung hon. * * @author Zara Ali * @version 1.0 * @since 2014-03-31 */ public class AddNum { /** * Phuong thuc nay duoc su dung de cong hai so. Day la * mot form don gian nhat cua phuong thuc, de minh hoa * cac su dung cua cac javadoc Tags. * @param numA Day la tham so dau tien cua phuong thuc addNum * @param numB Day la tham so thu hai cua phuong thuc addNum * @return int Tra ve tong cua numA va numB. */ public int addNum(int numA, int numB) { return numA + numB; } /** * Day la phuong thuc chinh ma su dung phuong thuc addNum. * @param args Unused. * @return Nothing. * @exception IOException On input error. * @see IOException */ public static void main(String args[]) throws IOException { AddNum obj = new AddNum(); int sum = obj.addNum(10, 20); System.out.println("Tong cua 10 va 20 la :" + sum); } }
Bây giờ, xử lý AddNum.java file bởi sử dụng tiện ích javadoc như sau:
$ javadoc AddNum.java Loading source file AddNum.java... Constructing Javadoc information... Standard Doclet version 1.7.0_51 Building tree for all the packages and classes... Generating /AddNum.html... AddNum.java:36: warning - @return tag cannot be used in method with void return type. Generating /package-frame.html... Generating /package-summary.html... Generating /package-tree.html... Generating /constant-values.html... Building index for all the packages and classes... Generating /overview-tree.html... Generating /index-all.html... Generating /deprecated-list.html... Building index for all classes... Generating /allclasses-frame.html... Generating /allclasses-noframe.html... Generating /index.html... Generating /help-doc.html... 1 warning $
Bạn có thể kiểm tra tất cả về Documentation đã tạo ở đây: AddNum. Nếu bạn đang sử dụng JDK 1.7 thì javadoc không tạo một stylesheet.css tốt, vì thế tôi đề nghị bạn tải và sử dụng Stylesheet từ http://docs.oracle.com/javase/7/docs/api/stylesheet.css
