Tạo Javadoc
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. |
Chương hướng dẫn này giải thích về Javadoc. Chúng ta sẽ thấy cách sử dụng Javadoc để tạo Documentation hữu ích cho Java code của bạn.
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
Đã có app VietJack trên điện thoại, giải bài tập SGK, SBT Soạn văn, Văn mẫu, Thi online, Bài giảng....miễn phí. Tải ngay ứng dụng trên Android và iOS.
Các bạn có thể mua thêm khóa học JAVA CORE ONLINE VÀ ỨNG DỤNG cực hay, giúp các bạn vượt qua các dự án trên trường và đi thực tập doanh nghiệp với Java. Khóa học có giá chỉ 400K, nhằm ưu đãi, tạo điều kiện cho sinh viên cho thể mua khóa học.
Nội dung khóa học gồm 16 chuơng và 100 video cực hay, học trực tiếp tại https://www.udemy.com/tu-tin-di-lam-voi-kien-thuc-ve-java-core-toan-tap/ Bạn nào có nhu cầu mua, inbox trực tiếp chị Thu, trợ lý anh Tuyền để hỗ trợ thanh toán qua mã QR ngân hàng Việt Nam, fb: https://www.facebook.com/Thule.59
Anh Tuyền, tác giả khóa học, là cựu sinh viên chương trình đào tạo kĩ sư tài năng của đại học Bách Khoa Hà Nội với hơn 5 năm kinh nghiệm đi làm thực tế doanh nghiệp và cũng là Founder website vietjack.com, web giáo dục phổ biến nhất Việt Nam hiện tại (năm 2024). Java cũng là ngôn ngữ lập trình dễ đi xin việc nhất hiện tại, với mức lương cao, hãy nâng cao kiến thức IT của bản thân mình vì một Việt Nam giàu mạnh.
Loạt bài hướng dẫn của chúng tôi dựa một phần trên nguồn tài liệu của: Tutorialspoint.com
Bài học Java phổ biến tại vietjack.com:
