Đào tạo Java - Java - Nhận xét tài liệu

Ngôn ngữ Java hỗ trợ ba loại ý kiến ​

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

Chương này là tất cả về việc giải thích Javadoc. Chúng ta sẽ thấy 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 theo định dạng HTML từ mã nguồn Java, yêu cầu tài liệu theo định dạng được xác định trước.

Học lập trình Java chuyên nghiệp

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

>> Khóa đào tạo java <<

/**
* 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 cần thiết bên trong phần mô tả. Chẳng hạn, ví dụ sau sử dụng <h1> .... </ h1> cho tiêu đề và <p> đã được sử dụng để tạo ngắt đoạn

/**
* <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 ra các thẻ sau

Nhãn	Sự miêu tả	Cú pháp
@ Tác giả	Thêm tác giả của một lớp.	@ Tác giả tên-văn bản
{@code}	Hiển thị văn bản ở phông chữ mã mà không diễn giải văn bản dưới dạng đánh dấu HTML hoặc các thẻ javadoc lồng nhau.	{@code văn bản}
{@docRoot}	Đại diện cho đường dẫn tương đối đế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}
@ phân biệt	Thêm một bình luận chỉ ra rằng API này sẽ không còn được sử dụng.	@deprecated deprecatedtext
@ngoại lệ	Thêm một phân nhóm Ném cho tài liệu được tạo, với tên lớp và văn bản mô tả.	@exception mô tả tên lớp
{@inheritDoc}	Kế thừa một nhận xét từ lớp kế thừa hoặc giao diện có thể thực hiện gần nhất .	Kế thừa một nhận xét từ lớp siêu nhân ngay lập tức.
{@link}	Chèn một liên kết nội tuyến 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 gói. class # nhãn thành viên}
{@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 phông chữ mã.	{@linkplain gói. class # nhãn thành viên}
@param	Thêm một tham số với tên tham số đã chỉ định, theo sau là mô tả đã chỉ định vào phần "Tham số".	@param mô tả tên tham số
@trở về	Thêm phần "Trả về" với văn bản mô tả.	mô tả @return
@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 doc cho trường tuần tự hóa mặc định.	@serial lĩnh vực mô tả | bao gồm | loại trừ
@serialData	Tài liệu dữ liệu được viết bởi các phương thức writeObject () hoặc writeExternal ().	@serialData mô tả dữ liệu
@serialField	Tài liệu một thành phần ObjectStreamField.	@serialField mô tả trường loại tên trường
@ hoàng tử	Thêm tiêu đề "Kể từ" với văn bản từ được chỉ định vào tài liệu được tạo.	@since phát hành
@throw	Các thẻ @throws và @exception là từ đồng nghĩa.	@throw mô tả tên lớp
{@giá trị}	Khi {@value} được sử dụng trong nhận xét tài liệu của trường tĩnh, nó sẽ hiển thị giá trị của hằng số đó.	{@value gói. class # field}
@phiên bản	Thêm một tiêu đề phụ "Phiên bản" với văn bản phiên bản đã chỉ định vào các tài liệu được tạo khi sử dụng tùy chọn đảo ngược.	@version phiên bản-văn bản

Chương trình sau sử dụng một vài thẻ quan trọng có sẵn để 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 bạn.

Tài liệu về lớp AddNum sẽ được tạo trong tệp HTML AddNum.html nhưng đồng thời, một 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 được tạo ở đây - AddNum . Nếu bạn đang sử dụng JDK 1.7 thì javadoc không tạo ra một biểu định kiểu tuyệt vời.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 tiêu chuẩn từ https://docs.oracle.com/javase/7/docs/api/stylesheet.css