Повторне використання Javadoc для перевантажених методів

Question 1

Я розробляю 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, яке має таку підтримку? Або є поважна причина, чому я не підтримав, що я пропустив?

Question 2

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

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

Question 3

Я б просто задокументував ваш "найповніший" метод (у цьому випадку 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 );

Question 4

Швидше за все, немає хорошого стандартного методу, оскільки навіть вихідний код JDK9 просто копіює великі фрагменти документації, наприклад, за адресою:

Повторюються 4 рядки коментарів. Так, несухо.

Question 5

Помістіть документацію в інтерфейс, якщо можете. Класи, що реалізують інтерфейс, успадкують 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));

Можливо, ви хочете поглянути на цей шаблон мутатора копіювання тут:

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

Залежно від кількості комбінацій параметрів це може бути простішим і чистішим способом, оскільки Params-Class може фіксувати за замовчуванням і мати javadoc для кожного параметра.