Метод переопределения документации Java не наследует

Метод, который переопределяет другой метод, не наследует документацию метода, который он переопределяет. Есть ли способ явно сказать ему, чтобы унаследовать документацию?

/**
  * {@inheritDoc}
  * 
  * This implementation uses a dynamic programming approach.
  */
@Override
public int[] a(int b) {
    return null;
}
Источник

3 ответа

Решение

Согласно документации Javadoc:

Наследование комментариев происходит во всех трех возможных случаях наследования от классов и интерфейсов:

  • Когда метод в классе переопределяет метод в суперклассе
  • Когда метод в интерфейсе переопределяет метод в суперинтерфейсе
  • Когда метод в классе реализует метод в интерфейсе

Комментарии могут быть явно унаследованы с помощью тега {@inheritDoc}. Если для переопределенного метода не предоставлено никаких комментариев, комментарии будут неявно наследоваться. Аспекты наследующих комментариев (например, params, возвращаемое значение и т. Д.) Могут быть переопределены, если вы того пожелаете.

Важно отметить, что вы должны убедиться, что исходный файл, содержащий код с комментарием для наследования, доступен для инструмента javadoc. Вы можете сделать это, используя опцию - sourcepath.

Источник

Из руководства по Javadoc 1.4.2

Алгоритм наследования комментариев к методу. Если метод не имеет комментария к документу или имеет тег {@inheritDoc}, инструмент Javadoc выполняет поиск подходящего комментария, используя следующий алгоритм, который предназначен для поиска наиболее конкретного применимого комментария к документу, отдавая предпочтение интерфейсам над суперклассами:

  1. Посмотрите в каждом непосредственно реализованном (или расширенном) интерфейсе в том порядке, в котором они появляются после слова внедряет (или расширяет) в объявлении метода. Используйте первый найденный комментарий для этого метода.
  2. Если на шаге 1 не удалось найти комментарий к документу, рекурсивно применить весь этот алгоритм к каждому непосредственно реализованному (или расширенному) интерфейсу в том же порядке, в котором они были рассмотрены на шаге 1.
  3. Если на шаге 2 не удалось найти комментарий к документу и это класс, отличный от Object (не интерфейс): 1. Если у суперкласса есть комментарий к документу для этого метода, используйте его. 2. Если на шаге 3a не удалось найти комментарий к документу, рекурсивно примените весь этот алгоритм к суперклассу.

Я полагаю (хотя я могу ошибаться), что этот базовый алгоритм по-прежнему применим к Java 1.5 и 1.6... хотя было бы очень приятно, если бы Sun опубликовала полный автономный окончательный документ для каждой версии набора инструментов... Я думаю, что это накладные расходы, которые они просто не могут себе позволить, по крайней мере, для бесплатного набора инструментов.

Приветствия. Кит.

Редактировать:

Вот быстрый и грязный пример.

Код

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}
     */
Источник
Другие вопросы по тегам