javadoc: @version i @since

Question

Czy jest jakiś powód, aby uwzględnić zarówno @version and @since jako część klasy?

Wygląda na to, że wzajemnie się wykluczają.

Co ponadto oznacza %I% and %G% i jak je ustawiać/używać?

@version %I%, %G% 

dzięki

Answer 1

Znacznik @version powinien być bieżącą wersją danego wydania lub pliku. Składnia %I%, %G% to makra, które oprogramowanie sterujące źródłem zastąpiłoby bieżącą wersją pliku oraz datą, w której plik zostanie wyewidencjonowany.

Znacznik @since powinien być użyty do zdefiniowania wersji, do której dodano metodę, klasę itp. Jest to wskazówka dla innych programistów, że powinni oni oczekiwać metody tylko wtedy, gdy działają przeciwko konkretnej wersji pakietu. Rozważę te ważne części dokumentacji, jeśli przesyłasz swój kod jako bibliotekę przeznaczoną dla kogoś innego.

Answer 2

nie widzę w jaki sposób są one wzajemnie się wykluczają. Jeden służy do definiowania wersji, a drugi służy do opisywania od kiedy istnieje metoda. Na przykład:

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

Odnośnie znaków, o których mowa, wydają zastrzeżone, aw każdym razie nie mam pojęcia, co one oznaczają.

Answer 3

@version będzie rekord każdy edycji. [01.03.21]

@since to znaczy, od której wersji release będzie wspierać ten interfejs lub itp [1,3] Yuval Adam jest interesująca, ale nie jest to średnia celem java doc jest każdy może zrozumieć.

Answer 4

Dobrze wyjaśnione w artykule z Oracle, How to Write Doc Comments for the Javadoc Tool.

@version

... Klasy i interfejsy tylko.

W oprogramowaniu Java używamy @version dla wersji SCCS. Zobacz "man sccs-get", aby poznać szczegóły. Konsensus wydaje się być następujące:

% I% zostanie zwiększona każdorazowo edytować i delget plik

% G% jest data dd/mm/rr

Podczas tworzenia pliku % I% jest ustawiony na 1,1. Kiedy edytujesz i usuniesz, zwiększa się do 1,2.

Niektórzy programiści pomijają datę% G% (i robili to), jeśli uznają to za zbyt mylące - na przykład 3/4/96, które% G% wytworzyłoby na 4 marca, byłoby interpretowane przez poza Stanami Zjednoczonymi oznacza 3 kwietnia. Niektórzy deweloperzy uwzględniają czas% U% tylko wtedy, gdy chcą uzyskać lepszą rozdzielczość (ze względu na wielokrotne kontrole w ciągu dnia).

Najczystsze numeryczny format daty byłoby mieć datę sformatowaną z pierwszego roku, coś rrrr-mm-dd, jak zaproponowano w ISO 8601 i gdzie indziej (jak http://www.cl.cam.ac.uk/~mgk25/iso-time.html), ale że poprawa musiałyby pochodzić z SCCS.

@since

Określ wersję produktu, gdy nazwa Java została dodana do specyfikacji API (jeżeli różni się od wykonania). Na przykład, jeśli pakiet, klasa, interfejs lub członek został dodany do Java 2 Platform, Standard Edition, API Specification w wersji 1.2, należy użyć:

/** 
* @since 1.2 
*/ 

Standardowa Javadoc doclet wyświetla komunikat „Od "Podtytuł z argumentem tekstowym jako tekstem. Podpozycja ta pojawia się w wygenerowanym tekście tylko w miejscu odpowiadającym miejscu, w którym znacznik @since pojawia się w źródłowych komentarzach do dokumentu (narzędzie Javadoc nie mnoży go w hierarchii).

(Konwencja kiedyś „@since JDK1.2”, ale ponieważ jest to specyfikacja platformy Java, nie szczególności Oracle JDK lub SDK, że spadły „JDK”).

Kiedy Pakiet jest wprowadzony, należy określić znacznik @since w jego opisie pakietu i każdej z jego klas. (Dodawanie znaczników @since do każdej klasy jest technicznie niepotrzebne, ale jest naszą konwencją, ponieważ umożliwia lepszą widoczność kodu źródłowego). W przypadku braku nadpisujących znaczników wartość znacznika @since odnosi się do każdej klasy pakietu i członków.

Po wprowadzeniu klasy (lub interfejsu) określ jeden znacznik @since w opisie klasy i brak znaczników @since w elementach. Dodaj znacznik @since tylko do członków dodanych w nowszej wersji niż klasa. Minimalizuje to liczbę tagów @since.

Jeśli członek zmieni się z chronionego na publiczny w późniejszym wydaniu, znacznik @since nie zmieniłby się, nawet jeśli teraz jest on dostępny dla każdego dzwoniącego, a nie tylko dla subklasserów.