Ant - Xây dựng Tài liệu

Tài liệu là bắt buộc trong bất kỳ dự án nào. Tài liệu đóng một vai trò lớn trong việc duy trì một dự án. Java làm cho tài liệu dễ dàng hơn bằng cách sử dụngjavadocdụng cụ. Ant làm cho nó thậm chí còn dễ dàng hơn bằng cách tạo tài liệu theo yêu cầu.

Như bạn đã biết, công cụ javadoc rất linh hoạt và cho phép một số tùy chọn cấu hình. Ant hiển thị các tùy chọn cấu hình này thông qua tác vụ javadoc. Nếu bạn không quen với javadocs, chúng tôi khuyên bạn nên bắt đầu với Hướng dẫn về Tài liệu Java này .

Phần sau đây liệt kê các tùy chọn javadoc thông dụng nhất được sử dụng trong Ant.

Thuộc tính

Nguồn có thể được chỉ định bằng cách sử dụng sourcepath, sourcepathref hoặc là sourcefiles.

sourcepath được sử dụng để trỏ đến thư mục của các tệp nguồn (ví dụ: thư mục src).
sourcepathref được sử dụng để tham chiếu một đường dẫn được tham chiếu bởi thuộc tính đường dẫn (ví dụ: Delegate.src.dir).
sourcefiles được sử dụng khi bạn muốn chỉ định các tệp riêng lẻ dưới dạng danh sách được phân tách bằng dấu phẩy.

Đường dẫn đích được chỉ định bằng cách sử dụng destdir thư mục (ví dụ: build.dir).

Bạn có thể lọc javadocnhiệm vụ bằng cách chỉ định các tên gói được đưa vào. Điều này đạt được bằng cách sử dụngpackagenames thuộc tính, danh sách các tệp gói được phân tách bằng dấu phẩy.

Bạn có thể lọc quy trình javadoc để chỉ hiển thị các lớp và thành viên công khai, riêng tư, gói hoặc được bảo vệ. Điều này đạt được bằng cách sử dụngprivate, public, package và protected thuộc tính.

Bạn cũng có thể yêu cầu nhiệm vụ javadoc bao gồm thông tin tác giả và phiên bản bằng cách sử dụng các thuộc tính tương ứng.

Bạn cũng có thể nhóm các gói lại với nhau bằng cách sử dụng group , để dễ dàng điều hướng.

Để tất cả chúng cùng nhau

Hãy để chúng tôi tiếp tục chủ đề của chúng tôi về Hello worldỨng dụng fax. Hãy để chúng tôi thêm mục tiêu tài liệu vào dự án ứng dụng Fax của chúng tôi.

Dưới đây là một tác vụ javadoc ví dụ được sử dụng trong dự án của chúng tôi. Trong ví dụ này, chúng tôi đã chỉ định javadoc để sử dụngsrc.dir làm thư mục nguồn và doc làm mục tiêu.

Chúng tôi cũng đã tùy chỉnh tiêu đề cửa sổ, thông tin đầu trang và chân trang xuất hiện trên các trang tài liệu java.

Ngoài ra, chúng tôi đã tạo ra ba nhóm -

một cho các lớp tiện ích trong thư mục nguồn của chúng tôi,
một cho các lớp giao diện người dùng và
một cho các lớp liên quan đến cơ sở dữ liệu.

Bạn có thể nhận thấy rằng nhóm gói dữ liệu có hai gói -– faxapp.entity và faxapp.dao.

<target name = "generate-javadoc">
   <javadoc packagenames = "faxapp.*" sourcepath = "${src.dir}" 
      destdir = "doc" version = "true" windowtitle = "Fax Application">
      
      <doctitle><![CDATA[= Fax Application =]]></doctitle>
      
      <bottom>
         <![CDATA[Copyright © 2011. All Rights Reserved.]]>
      </bottom>
      
      <group title = "util packages" packages = "faxapp.util.*"/>
      <group title = "web packages" packages = "faxapp.web.*"/>
      <group title = "data packages" packages = "faxapp.entity.*:faxapp.dao.*"/>
   </javadoc>

   <echo message = "java doc has been generated!" />
</target>

Hãy để chúng tôi thực hiện nhiệm vụ javadoc Ant. Nó tạo và đặt các tệp tài liệu java trong thư mục doc.

Khi mà javadoc target được thực thi, nó tạo ra kết quả sau:

C:\>ant generate-javadoc
Buildfile: C:\build.xml

java doc has been generated!

BUILD SUCCESSFUL
Total time: 10.63 second

Các tệp tài liệu java hiện có trong doc thư mục.

Thông thường, các tệp javadoc được tạo như một phần của mục tiêu gói hoặc bản phát hành.