Java - Конвенция для использования javadoc вместе с аннотацией метода?
У меня есть следующий метод:
@Override
public boolean myMethod()
{
// do stuff
}
Если я хочу добавить javadoc для этого метода, существует ли какое-либо соглашение о том, как это сделать, а также аннотацию @Override (или любую другую аннотацию)?
Причина, по которой я спрашиваю, заключается в том, что я прочитал, что комментарии javadoc ДОЛЖНЫ быть непосредственно перед этим методом (между ними нет новых строк), и я не уверен, что если комментарий javadoc непосредственно над аннотацией @Override будет беспорядочным вверх.
Будет ли это обычный способ сделать это, например? Это работает?
/**
* This is my method javadoc comment.
*/
@Override
public boolean myMethod()
{
// do stuff
}
Ответы
Ответ 1
Да, этот путь - это правильный путь, я еще не видел другого пути. И да, так оно и работает. Не пробовал наоборот.
/**
* This is my method javadoc comment.
*/
@Override
public boolean myMethod()
{
// do stuff
}
Но в основном я обычно не добавлял комментарий javadoc к методу, который переопределяет другой метод, особенно при реализации интерфейсов. Тег @inheritDoc
полезен здесь, чтобы распространять документацию без больших усилий. Но это специфично для этого примера, вы можете добавить и другие аннотации.
Ответ 2
Да, он будет работать правильно. Например, в исходный код java.lang.String из openjdk они используют javadoc поверх аннотации @Deprecated
.