Повторное использование 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 должны знать о добавлении деревьев hold for all данные методы.

В идеале, я хотел бы написать один блок 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 63
javascript javadoc

4 ответа:

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

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

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

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

4 линии комментарии повторяются. Фу, не-сухость.

4

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

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-класс может захватывать значения по умолчанию и иметь javadoc для каждого параметра.

0