Метод, который переопределяет другой метод, не наследует документацию о методе, который он переопределяет. Есть ли способ явно указать ему наследовать документацию?
/**
* {@inheritDoc}
*
* This implementation uses a dynamic programming approach.
*/
@Override
public int[] a(int b) {
return null;
}
В соответствии с документацией javadoc:
Наследование комментариев происходит во всех три возможных случая наследования из классов и интерфейсов:
- Когда метод класса переопределяет метод в суперклассе
- Когда метод в интерфейсе переопределяет метод в суперинтерфейсе
- Когда метод в классе реализует метод в интерфейсе
Комментарии могут быть явно унаследованы с помощью тега {@inheritDoc}. Если для переопределяющего метода не предоставляются комментарии, комментарии будут неявно унаследованы. Аспекты наследующих комментариев (например, params, return value и т.д.) Могут быть отменены, если вы этого захотите.
Важно отметить, что вам нужно убедиться, что исходный файл, содержащий код с наследуемым комментарием, доступен для инструмента javadoc. Вы можете сделать это, используя опцию - sourcepath.
Алгоритм для комментариев метода наследования. Если метод не имеет комментария к документу или имеет тег {@inheritDoc}, инструмент Javadoc ищет соответствующий комментарий, используя следующий алгоритм, который разработанный, чтобы найти наиболее специфический комментарий к документу, отдавая предпочтение интерфейсам над суперклассами:
- Посмотрите в каждом непосредственно реализованном (или расширенном) интерфейсе в том порядке, в котором они появляются после слова, реализующего (или расширяет) в объявлении метода. Используйте первый комментарий к документу, найденный для этого метода.
- Если на этапе 1 не удалось найти комментарий к документу, рекурсивно применить весь этот алгоритм к каждому непосредственно реализованному (или расширенному) интерфейсу в том же порядке, который был рассмотрен на шаге 1.
- Если на этапе 2 не удалось найти комментарий к доктору, и это класс, отличный от Object (а не интерфейс): 1. Если у суперкласса есть комментарий для этого метода, используйте его. 2. Если на этапе 3a не удалось найти комментарий к документу, рекурсивно применить весь этот алгоритм к суперклассу.
Я считаю (хотя я мог ошибаться), что этот базовый алгоритм по-прежнему применяется к Java 1.5 и 1.6... хотя было бы очень приятно, чтобы Sun опубликовала полный автономный окончательный документ для каждой версии набора инструментов... Я думаю, это накладные расходы, которые они просто не могут себе позволить, по крайней мере, для бесплатного набора инструментов.
Приветствия. Кит.
Edit:
Вот быстрый и грязный пример.
код
package forums;
interface Methodical
{
/**
* A no-op. Returns null.
* @param i int has no effect.
* @return int[] null.
*/
public int[] function(int i);
}
interface Methodological extends Methodical
{
/**
* Another no-op. Does nothing.
*/
public void procedure();
}
class Parent implements Methodological
{
@Override
public int[] function(int i) {
return null;
}
@Override
public void procedure() {
// do nothing
}
}
class Child extends Parent
{
/** {@inheritDoc} */
@Override
public int[] function(int i) {
return new int[0];
}
/** {@inheritDoc} */
@Override
public void procedure() {
System.out.println("I'm a No-op!");
}
}
public class JavaDocTest
{
public static void main(String[] args) {
try {
new Child().procedure();
} catch (Exception e) {
e.printStackTrace();
}
}
}
Javadoc
C:\Java\home\src\forums>javadoc -package -sourcepath . JavaDocTest.java
Loading source file JavaDocTest.java...
Constructing Javadoc information...
Standard Doclet version 1.6.0_12
Building tree for all the packages and classes...
Generating forums/\Child.html...
Generating forums/\JavaDocTest.html...
Generating forums/\Methodical.html...
Generating forums/\Methodological.html...
Generating forums/\Parent.html...
Generating forums/\package-frame.html...
Generating forums/\package-summary.html...
Generating forums/\package-tree.html...
Generating constant-values.html...
Building index for all the packages and classes...
Generating overview-tree.html...
Generating index-all.html...
Generating deprecated-list.html...
Building index for all classes...
Generating allclasses-frame.html...
Generating allclasses-noframe.html...
Generating index.html...
Generating help-doc.html...
Generating stylesheet.css...
Производит файл:///C:/Java/home/src/forums/index.html
function
public int[] function(int i)
A no-op. Returns null.
Specified by:
function in interface Methodical
Overrides:
function in class Parent
Parameters:
i - int has no effect.
Returns:
int[] null.
procedure
public void procedure()
Another no-op. Does nothing.
Specified by:
procedure in interface Methodological
Overrides:
procedure in class Parent
Сменить @Override с помощью javaDoc.
@Override
/**
* {@inheritDoc}
*/