Повторное использование 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 должны знать о добавляющих деревьях, содержат для всех этих методов.
Идеально, я хотел бы записать один блок 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, если я понимаю это правильно, все, которое я могу сделать, по существу copy&paste тот же javadoc блок пять раз, только с немного отличающимся списком параметров для каждого метода. Это звучит громоздким мне и также трудно поддержать.
Есть ли какой-либо путь вокруг этого? Некоторое расширение javadoc, который имеет этот вид поддержки? Или есть ли серьезное основание, почему это не поддерживается, что я отсутствовал?
2 ответа
Я не знаю какой-либо поддержки, но я бы полностью написал 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 );