Jak píšete javadoc u implementací rozhraní nebo u překrytých metod? Léta jsem používal výchozí generovaný javadoc v Eclipse

(non-Javadoc) @see

, později jsem přešel na standardní

{@inheritDoc}

Nedávno jsem si na twitteru stěžoval, že v Intellij Idea není možné si potřebnou šablonu upravit. Připadám si jak z té historky, ve které dcera celý život pekla štrúdl tak, že vždy před vložením na plech zařízla patky, protože to tak pokaždé dělala i její matka. Předpokládala, že je to součást receptu, že to tak bude prostě lepší. Ovšem matka to dělalal proto, že měla malý plech a štrúdl by se jí tam celý nevešel.

Zjistil jsem, že Idea má svůj důvod, proč šablonu nelze upravit; javadoc se totiž kopíruje automaticky, takže se lze bez tohoto balastu obejít. Jeden případ, kdy by se vám mohla direktiva

{@inheritDoc}

hodit je ten, kdy chcete zkopírovat javadoc a přidat nějaký specifický popis. V ukázce je to metoda

add()

Eclipse i Idea tohle chování podporují, ale javadoc vygenerovaný z příkazové řádky (ať už Mavenem či čistě z Javy) ho prostě přepíše - chová se stejně, jako by tam nebyl žádný

{@inheritDoc}

Kód

public interface Sample {
/**
* Some javadoc.
*/
void doSomething();
/**
* Another javadoc.
*/
void doSomethingElse();
/**
* Different javadoc.
*/
void doNothing();
/**
* This javadoc will be replaced.
*/
void replace();
/**
* This javadoc will be extended.
*/
void add();
}
view raw Sample.java hosted with ❤ by GitHub
public class SampleImpl implements Sample {
@Override
public void doSomething() {
//TODO
}
/**
* {@inheritDoc}
*/
@Override
public void doSomethingElse() {
//TODO
}
/*
* (non-Javadoc)
*
* @see Sample#doNothing()
*/
@Override
public void doNothing() {
//TODO
}
/**
* This replaces the original javadoc.
*/
@Override
public void replace() {
//TODO
}
/**
* Some additional comments. {@inheritDoc}
*/
@Override
public void add() {
//TODO
}
}
view raw SampleImpl.java hosted with ❤ by GitHub

Javadoc v IDE

HTML javadoc

Empiricky zjištěno: Idea, Eclipse i generovaný javadoc u implementace rozhraní kopíruje javadoc ať už použijete konstrukci

(non-Javadoc) @see

, případně

{@inheritDoc}

nebo dokonce vůbec nic, což je nakonec zdaleka nejlepší, ne?