javadoc: @version and @since

Question

Có lý do gì để bao gồm cả hai @version and @since như là một phần của lớp học không?

Chúng dường như loại trừ lẫn nhau.

Ngoài ra, ý nghĩa của %I% and %G% là gì và cách đặt/sử dụng chúng?

@version %I%, %G% 

nhờ

Answer 1

Thẻ @version phải là phiên bản hiện tại của bản phát hành hoặc tệp được đề cập. Cú pháp %I%, %G% là các macro mà phần mềm điều khiển nguồn sẽ thay thế bằng phiên bản hiện tại của tệp và ngày tệp được kiểm tra.

Thẻ @since nên được sử dụng để xác định phiên bản bạn đã thêm phương thức, lớp, v.v. Đây là gợi ý của bạn cho các nhà phát triển khác rằng họ chỉ nên mong đợi phương pháp khi họ chạy với phiên bản cụ thể của gói. Tôi sẽ xem xét những phần quan trọng này của tài liệu nếu bạn đang chuyển mã của mình dưới dạng thư viện dành cho người khác sử dụng.

Answer 2

tôi không thấy cách họ loại trừ lẫn nhau. Một được sử dụng để xác định phiên bản, và cái kia được sử dụng để mô tả kể từ khi phương pháp có ở đó. Ví dụ:

/** 
* Does Whatever 
* @version 1.2.3 
* @since 1.2.0 
* 
*/ 
public void myMethod() { 
    // ....... 
} 

Về các ký tự bạn đã đề cập, chúng có vẻ độc quyền và trong bất kỳ trường hợp nào tôi không hiểu ý nghĩa của chúng.

Answer 3

@version sẽ ghi lại mọi chỉnh sửa. [1.3.21]

@since là có nghĩa là kể từ đó phát hành phiên bản sẽ được hỗ trợ giao diện này hoặc vv [1.3] Yuval Adam là thú vị, nhưng đây không phải là tiêu chuẩn , mục đích của java doc là mọi người đều có thể hiểu được.

Answer 4

Giải thích rõ trong một bài viết từ Oracle, How to Write Doc Comments for the Javadoc Tool.

@version

... lớp và giao diện duy nhất.

Tại Java Software, chúng tôi sử dụng @version cho phiên bản SCCS. Xem "man sccs-get" để biết chi tiết. Sự đồng thuận có vẻ là như sau:

% I% được tăng lên mỗi khi bạn chỉnh sửa và delget một file

% G% là ngày dd/mm/yy

Khi bạn tạo một tập tin, % I% được đặt thành 1.1. Khi bạn chỉnh sửa và xóa nó, nó sẽ tăng lên 1,2.

Một số nhà phát triển bỏ qua ngày% G% (và đã làm như vậy) nếu họ thấy quá khó hiểu - ví dụ: 3/4/96, mà% G% sẽ tạo cho ngày 4 tháng 3, sẽ được giải thích bởi những người bên ngoài Hoa Kỳ có nghĩa là ngày 3 tháng Tư. Một số nhà phát triển chỉ bao gồm thời gian% U% nếu họ muốn có độ phân giải tốt hơn (do nhiều lần đăng ký trong một ngày).

Định dạng ngày số rõ ràng nhất sẽ là ngày được định dạng với năm đầu tiên, như yyyy-mm-dd, như được đề xuất trong ISO 8601 và các nơi khác (chẳng hạn như http://www.cl.cam.ac.uk/~mgk25/iso-time.html), nhưng cần phải tăng cường SCCS.

@since

Xác định phiên bản sản phẩm khi tên Java đã được thêm vào đặc điểm kỹ thuật API (nếu khác với việc thực hiện). Ví dụ, nếu một gói, lớp, giao diện hoặc thành viên được thêm vào 2 nền tảng Java, Standard Edition, Đặc điểm kỹ thuật API tại phiên bản 1.2, sử dụng:

/** 
* @since 1.2 
*/ 

Tiêu chuẩn Javadoc Doclet sẽ hiển thị một "Kể từ "phân nhóm bằng đối số chuỗi làm văn bản của nó. Phân nhóm này chỉ xuất hiện trong văn bản được tạo ra ở vị trí tương ứng với vị trí thẻ @since xuất hiện trong các chú thích doc nguồn (Công cụ Javadoc không sinh sôi nó xuống phân cấp).

(Quy ước một lần được "@since JDK1.2" nhưng vì đây là một đặc điểm kỹ thuật của nền tảng Java, không đặc biệt đến Oracle JDK hoặc SDK, chúng tôi đã giảm "JDK".)

Khi một gói được giới thiệu, chỉ định một thẻ @since trong mô tả gói của nó và mỗi lớp của nó. (Việc thêm thẻ @since vào mỗi lớp là không cần thiết về mặt kỹ thuật, nhưng là quy ước của chúng tôi, vì cho phép hiển thị nhiều hơn trong mã nguồn.) Trong trường hợp không có thẻ ghi đè, giá trị của thẻ @since áp dụng cho từng lớp của gói và các thành viên.

Khi lớp học (hoặc giao diện) được giới thiệu, chỉ định một thẻ @since trong mô tả lớp học và không có thẻ @since trong các thành viên. Chỉ thêm thẻ @since vào các thành viên được thêm vào trong phiên bản sau hơn lớp. Điều này giảm thiểu số lượng thẻ @since.

Nếu thành viên thay đổi từ được bảo vệ thành công khai trong bản phát hành sau, thẻ @since sẽ không thay đổi, mặc dù hiện tại mọi người có thể sử dụng được bất kỳ người gọi nào.