Повторное использование Javadoc для и перегруженных методов

Я разрабатываю API со многими идентично названными методами, которые отличаются только сигнатурой, что, я думаю, довольно распространено. Все они делают то же самое, за исключением того, что они инициализируют различные значения по умолчанию, если пользователь не хочет указывать. В качестве удобоваримого примера рассмотрим

public interface Forest
{
  public Tree addTree();

  public Tree addTree(int amountOfLeaves);

  public Tree addTree(int amountOfLeaves, Fruit fruitType);

  public Tree addTree(int amountOfLeaves, int height);

  public Tree addTree(int amountOfLeaves, Fruit fruitType, int height);
}

Существенное действие, выполняемое всеми этими методами, одинаково; дерево посажено в лесу. Многие важные вещи, которые пользователи моего API должны знать о добавлении деревьев для всех этих методов.

В идеале я хотел бы написать один блок Javadoc, который используется всеми методами:

  /**
   * Plants a new tree in the forest. Please note that it may take
   * up to 30 years for the tree to be fully grown.
   *
   * @param amountOfLeaves desired amount of leaves. Actual amount of
   * leaves at maturity may differ by up to 10%.
   * @param fruitType the desired type of fruit to be grown. No warranties
   * are given with respect to flavour.
   * @param height desired hight in centimeters. Actual hight may differ by
   * up to 15%.
   */

В моем воображении инструмент мог магически выбирать, какой из @params применим к каждому из методов, и таким образом генерировать хорошие документы для всех методов сразу.

С Javadoc, если я правильно его понимаю, все, что я могу сделать, это, по сути, копировать и вставлять один и тот же блок javadoc пять раз, имея только немного отличающийся список параметров для каждого метода. Это звучит громоздко для меня, и его также трудно поддерживать.

Есть ли какой-нибудь способ? Некоторое расширение для javadoc, у которого такая поддержка? Или есть веская причина, почему это не поддерживается, что я пропустил?

Ответ 1

Я не знаю никакой поддержки, но я бы полностью javadoc метод с большинством аргументов, а затем ссылаюсь на него в другом javadoc, как это. Я думаю, что он достаточно ясен и избегает избыточности.

/**
 * {@code fruitType} defaults to {@link FruitType#Banana}.
 *
 * @see Forest#addTree(int, Fruit, int)
 */

Ответ 2

Я бы просто задокументировал ваш "самый полный" метод (в данном случае addTree(int,Fruit,int)), а затем в JavaDoc для других методов ссылается на это и объясняет, как/какие значения по умолчанию используются для аргументов, не предоставленных.

/**
 * Works just like {@link ThisClass#myPow(double,double)} except the exponent is always 
 * presumed to be 2. 
 *
 * @see ThisClass#myPow(double,double)
 */
 static double myPow( double base );

Ответ 3

Вероятно, нет хорошего стандартного метода, так как даже исходный код JDK9 просто копирует пасты больших кусков документации вокруг, например, по адресу:

Повторяются 4 строки комментария. Yikes, non-DRYness.

Ответ 4

Поместите документацию в интерфейс, если сможете. Классы, реализующие интерфейс, затем наследуют javadoc.

interface X(){
 /** does fooish things */
 void foo();
}

class Ax implements X{ //automatically inherits the Javadoc of "X"
 @Override 
 public void foo(){/*...*/} 
}

Если вы хотите наследовать документацию и добавить к ней свои собственные материалы, вы можете использовать {@inheritDoc}:

class Bx implements X{
 /**
  * {@inheritDoc}
  * May fail with a RuntimeException, if the machine is too foo to be true.
  */
 @Override 
 public void foo(){/*...*/}
}

См. также: http://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#inheritingcomments

Теперь, когда я понял, это не совсем то, что вы хотите (вы хотите избежать повторений среди методов в одном классе/интерфейсе). Для этого вы можете использовать @see или @link, как описано другими, или вы можете подумать о своем дизайне. Возможно, вы хотите избежать перегрузки метода и использовать один метод с объектом параметра, например:

public Tree addTree(TreeParams p);

Используется следующим образом:

forest.addTree(new TreeParams().with(Fruits.APPLE).withLeaves(1500).withHeight(5));

Вам может понравиться этот шаблон copy-mutator здесь:

https://brixomatic.wordpress.com/2010/03/10/dealing-with-immutability-and-long-constructors-in-a-fluent-way/

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