Я разрабатываю 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, у которого такая поддержка? Или есть веская причина, почему это не поддерживается, что я пропустил?
Я не знаю никакой поддержки, но я бы полностью javadoc метод с большинством аргументов, а затем ссылаюсь на него в другом javadoc, как это. Я думаю, что он достаточно ясен и избегает избыточности.
/**
* {@code fruitType} defaults to {@link FruitType#Banana}.
*
* @see Forest#addTree(int, Fruit, int)
*/
Я бы просто задокументировал ваш "самый полный" метод (в данном случае 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 );
Вероятно, нет хорошего стандартного метода, так как даже исходный код JDK9 просто копирует пасты больших кусков документации вокруг, например, по адресу:
Повторяются 4 строки комментария. Yikes, non-DRYness.
Поместите документацию в интерфейс, если сможете. Классы, реализующие интерфейс, затем наследуют 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 здесь:
В зависимости от количества комбинаций параметров это может быть более простым и понятным способом, поскольку Params-Class может захватывать значения по умолчанию и иметь javadoc для каждого параметра.