Java - Nhận xét về Tài liệu

Ngôn ngữ Java hỗ trợ ba loại nhận xét:

Sr.No.	Nhận xét & Mô tả
1	/* text */ Trình biên dịch bỏ qua mọi thứ từ / * đến * /.
2	//text Trình biên dịch bỏ qua mọi thứ từ // đến cuối dòng.
3	/** documentation */ Đây là một nhận xét tài liệu và nói chung nó được gọi là doc comment. CácJDK javadoccông cụ sử dụng chú thích tài liệu khi chuẩn bị tài liệu được tạo tự động.

Chương này là tất cả về giải thích Javadoc. Chúng ta sẽ xem cách chúng ta có thể sử dụng Javadoc để tạo tài liệu hữu ích cho mã Java.

Javadoc là gì?

Javadoc là một công cụ đi kèm với JDK và nó được sử dụng để tạo tài liệu mã Java ở định dạng HTML từ mã nguồn Java, công cụ này yêu cầu tài liệu ở định dạng được xác định trước.

Sau đây là một ví dụ đơn giản trong đó các dòng bên trong /*….*/ là các chú thích nhiều dòng của Java. Tương tự, dòng đứng trước // là chú thích một dòng của Java.

Thí dụ

/**
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
*
* @author  Zara Ali
* @version 1.0
* @since   2014-03-31 
*/
public class HelloWorld {

   public static void main(String[] args) {
      // Prints Hello, World! on standard output.
      System.out.println("Hello World!");
   }
}

Bạn có thể bao gồm các thẻ HTML bắt buộc bên trong phần mô tả. Ví dụ: ví dụ sau sử dụng <h1> .... </h1> cho tiêu đề và <p> được sử dụng để tạo ngắt đoạn -

Thí dụ

/**
* <h1>Hello, World!</h1>
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
* <p>
* Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
* 
*
* @author  Zara Ali
* @version 1.0
* @since   2014-03-31 
*/
public class HelloWorld {

   public static void main(String[] args) {
      // Prints Hello, World! on standard output.
      System.out.println("Hello World!");
   }
}

Các thẻ javadoc

Công cụ javadoc nhận dạng các thẻ sau:

Nhãn	Sự miêu tả	Cú pháp
@author	Thêm tác giả của một lớp.	@author name-text
{@code}	Hiển thị văn bản trong phông chữ mã mà không hiểu văn bản dưới dạng đánh dấu HTML hoặc các thẻ javadoc lồng nhau.	{@code text}
{@docRoot}	Đại diện cho đường dẫn liên quan đến thư mục gốc của tài liệu được tạo từ bất kỳ trang nào được tạo.	{@docRoot}
@deprecated	Thêm nhận xét cho biết rằng API này không còn được sử dụng nữa.	@deprecated không được dùng nữa
@ngoại lệ	Thêm một Throws tiêu đề phụ của tài liệu đã tạo, với tên lớp và văn bản mô tả.	@exception class-name description
{@inheritDoc}	Kế thừa một nhận xét từ nearest lớp kế thừa hoặc giao diện có thể triển khai.	Kế thừa nhận xét từ lớp thay thế ngay lập tức.
{@link}	Chèn một liên kết nội dòng với nhãn văn bản hiển thị trỏ đến tài liệu cho gói, lớp hoặc tên thành viên được chỉ định của một lớp được tham chiếu.	{@link package.class # member label}
{@linkplain}	Giống hệt với {@link}, ngoại trừ nhãn của liên kết được hiển thị bằng văn bản thuần túy hơn là phông chữ mã.	{@linkplain package.class # member label}
@param	Thêm một tham số với tên tham số được chỉ định, theo sau là mô tả được chỉ định vào phần "Tham số".	@param tham số-tên mô tả
@trở về	Thêm phần "Trả lại" với văn bản mô tả.	@return mô tả
@xem	Thêm tiêu đề "Xem thêm" với một liên kết hoặc mục nhập văn bản trỏ đến tham chiếu.	@see tham khảo
@serial	Được sử dụng trong nhận xét tài liệu cho trường có thể tuần tự hóa mặc định.	@serial field-description | bao gồm | loại trừ
@serialData	Ghi lại dữ liệu được ghi bởi phương thức writeObject () hoặc writeExternal ().	@serialData data-description
@serialField	Tài liệu một thành phần ObjectStreamField.	@serialField trường-tên trường-loại trường-mô tả
@từ	Thêm tiêu đề "Kể từ" với văn bản kể từ được chỉ định vào tài liệu được tạo.	@since phát hành
@throws	Các thẻ @throws và @exception là các từ đồng nghĩa.	@throws class-name description
{@giá trị}	Khi {@value} được sử dụng trong nhận xét doc của trường tĩnh, nó sẽ hiển thị giá trị của hằng số đó.	{@value package.class # field}
@phiên bản	Thêm tiêu đề phụ "Phiên bản" với văn bản phiên bản được chỉ định vào tài liệu được tạo khi tùy chọn -version được sử dụng.	@version version-text

Thí dụ

Chương trình sau sử dụng một số thẻ quan trọng có sẵn cho các nhận xét tài liệu. Bạn có thể sử dụng các thẻ khác dựa trên yêu cầu của mình.

Tài liệu về lớp AddNum sẽ được tạo trong tệp HTML AddNum.html nhưng đồng thời tệp chính có tên index.html cũng sẽ được tạo.

import java.io.*;

/**
* <h1>Add Two Numbers!</h1>
* The AddNum program implements an application that
* simply adds two given integer numbers and Prints
* the output on the screen.
* <p>
* <b>Note:</b> Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
*
* @author  Zara Ali
* @version 1.0
* @since   2014-03-31
*/
public class AddNum {
   /**
   * This method is used to add two integers. This is
   * a the simplest form of a class method, just to
   * show the usage of various javadoc Tags.
   * @param numA This is the first paramter to addNum method
   * @param numB  This is the second parameter to addNum method
   * @return int This returns sum of numA and numB.
   */
   public int addNum(int numA, int numB) {
      return numA + numB;
   }

   /**
   * This is the main method which makes use of addNum method.
   * @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("Sum of 10 and 20 is :" + sum);
   }
}

Bây giờ, xử lý tệp AddNum.java ở trên bằ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ả các tài liệu đã tạo tại đây - AddNum . Nếu bạn đang sử dụng JDK 1.7 thì javadoc không tạo ra mộtstylesheet.css, vì vậy chúng tôi khuyên bạn nên tải xuống và sử dụng biểu định kiểu chuẩn từ https://docs.oracle.com/javase/7/docs/api/stylesheet.css