komentarze Interfejs JavaDoc

Question

Mam interfejs A, który ma metody x, y oraz z. Komentuję tę klasę w ten sposób:

/** 
* 
* A.java 
* Interface class that has the following methods. 
* 
* @author MyName 
* @since mm-dd-yyyy 
*/ 

public interface A { 

    //method description for x 
    void x(); 

    //method description for y 
    void y(); 

    //method description for z 
    void z(); 
} 

Czy to prawda, czy powinienem dodać inne rzeczy do KOMUNIKATÓW KLASY?

Answer 1

Tak, powinieneś napisać odpowiednie komentarze Javadoc do swoich interfejsów, aby jasno określić motywy interfejsu i jaki jest kontrakt zarówno dla osób dzwoniących, jak i implementujących.

Spójrz na niektóre z interfejsów w kodzie JDK na przykładach, jak java.util.List

Answer 2

Nie, nie podano żadnych komentarzy do JavaDoc dla metod. W jaki sposób ktoś używający lub implementujący interfejs powinien wiedzieć, jakie metody mają wykonywać? należy użyć odpowiednich opisów javadoc:

/** 
* This method fromulgates the wibble-wrangler. It should not be called without 
* first saturating all glashnashers. 
*/ 
void x(); 

pamiętać, że w przeciwieństwie do większości JavaDoc którego celem jest rozmówców, dokumentacja interfejs ma dwie grupy odbiorców: rozmówców i realizatorów. Musisz jasno określić, jakie strony mogą oczekiwać i jak powinny się zachowywać. Tak, jest to trudne do zrobienia dobrze :(

EDIT: Jeśli chodzi o komentarze na najwyższym poziomie.

• Osobiście bym pozbyć tagu @author, gdyż rzadko przydatna IMO (zwykle patrząc w kontroli źródła jest bardziej odpowiedni ...)
• Chyba faktycznie mają znaczący politykę wersjonowania (nie tylko daty), chciałbym pozbyć tagu @since.
• nie ma sensu podając źródło plik
• Opis "Klasa interfejsu, która ma następujące metody" jest bez znaczenia, sprzeczne (i) (interfejs nie jest klasą). Ktokolwiek czyta JavaDoc, będzie już mógł zobaczyć listę metod. Powinieneś próbować dostarczyć dodatkowe informacje tutaj.

Podobnie jak w przypadku normalnej dokumentacji klasowej, dokumentacja interfejsu powinna określać cel tego typu - jego rolę w szerszym schemacie rzeczy, być może przykład tego, jak ma być użyty, itp. Zobacz przykłady w JDK dla ogólnie rozsądnej wersji JavaDoc.