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

Question

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

Answer 1

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

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

Answer 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); 

Answer 3

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

• http://hg.openjdk.java.net/jdk9/jdk9/jdk/file/07175dc5b2da/src/java.desktop/share/classes/java/awt/Container.java#l417
• http://hg.openjdk.java.net/jdk9/jdk9/jdk/file/07175dc5b2da/src/java.desktop/share/classes/java/awt/Container.java#l464

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

Answer 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)); 

Вы хотели бы иметь смотреть на эту копию-мутаторный узор здесь:

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

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