Proprio come non si copia e incolla tutti i metodi dalla superclasse durante la scrittura del codice, quindi non si dovrebbe copiare e incollare tutta la documentazione quando si documentano metodi sovrascritti.
Da javadoc a docs.oracle.com :
{@inheritDoc}
Inherits (copies) documentation from the "nearest" inheritable class or implementable interface into the current doc comment at this tag's location. This allows you to write more general comments higher up the inheritance tree, and to write around the copied text.
This tag is valid only in these places in a doc comment:
- In the main description block of a method. In this case, the main description is copied from a class or interface up the hierarchy.
- In the text arguments of the
@return, @param and @throws tags of a method. In this case, the tag text is copied from the corresponding tag up the hierarchy.
See Automatic Copying of Method Comments for a more precise description of how comments are found in the inheritance hierarchy. Note that if this tag is missing, the comment is or is not automatically inherited according to rules described in that section.
E così, si eredita la documentazione dalla superclasse. Se la documentazione della superclasse si aggiorna, anche la tua lo fa.
Proprio come con l'ereditarietà del codice, puoi estendere i commenti.
Vediamo come appaiono le cose in un IDE e codice ...
public interface IFace {
/**
* This is a method.
*/
public void method1();
/**
* This is also a method
*/
public void method2();
}
Questa è solo un'interfaccia con alcuni javadoc e due metodi.
Consente a una classe di implementare questo ...
public class CClass implements IFace {
/**
* {@inheritDoc}
* This just returns.
*/
public void method1() {
}
public void method2() {
}
}
E poi i javadoc stessi:
public void method1()
This is a method. This just returns.
Specified by:
method1 in interface IFace
img
public void method2()
Description copied from interface: IFace This is also a method
Specified by:
method2 in interface IFace
img
La prima cosa da vedere è che con method1 , javadoc è incluso ed esteso con {@inheritdoc} . Tuttavia, no javadoc erediterà anche javadoc da qualsiasi luogo.
Se non stai cambiando il javadoc, non specificarlo. Lascia che l'IDE faccia la sua cosa. Lascia che anche la generazione automatica di javadoc faccia il suo dovere. Copiare e incollare la documentazione può essere altrettanto brutto di copiare e incollare il codice in quanto viola DRY e può portare alla documentazione della superclasse o dell'interfaccia sfuggire alla documentazione del metodo.
D'altro canto, se vuoi scrivere qualcosa di più, eredita la documentazione e scrivila.
