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

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

68 голосов
/ 01 апреля 2010

Я разрабатываю 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, которое имеет такую ​​поддержку? Или есть веская причина, почему это не поддерживается, что я пропустил?

Ответы [ 4 ]

62 голосов
/ 01 апреля 2010

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

/**
 * {@code fruitType} defaults to {@link FruitType#Banana}.
 *
 * @see Forest#addTree(int, Fruit, int)
 */
10 голосов
/ 01 апреля 2010

Я бы просто задокументировал ваш «самый полный» метод (в данном случае 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 );
5 голосов

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

4 строки комментария повторяются. Yikes, не СУХОЙ.

0 голосов
/ 20 апреля 2016

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

...