Tạo Javadoc

Ngôn ngữ Java hỗ trợ 3 kiểu comment sau:

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:

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