Как я могу добавить Javadoc в статический инициализатор в Java?

Question

Я произвел рефакторинг класса и переместил некоторый код из конструктора в статический инициализатор. Что я должен сделать с Javadoc, который был на конструкторе? Можно ли добавить javadoc в статический инициализатор?

Answer 1

В первую очередь, это спорно, если статические инициализаторы являются хорошей практикой, чтобы начать с.

Если вы все же решите их использовать, я добавлю документацию в JavaDoc на уровне класса . Статические инициализаторы могут, в зависимости от того, как они реализованы, вызывать побочные эффекты. Если вы используете статические инициализаторы с побочными эффектами, поведение должно быть задокументировано для потребителя указанного класса.

Answer 2

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

Статический инициализатор не является частью интерфейса. Это часть реализации класса.

При желании вы можете задокументировать его поведение в документации класса.

Answer 3

В Java не существует статического конструктора ( в отличие от C # ), поэтому вы должны задокументировать это поведение на уровне класса.

Кроме того, посколькуСтатический инициализатор, скорее всего, инициализирует некоторые статические поля. Если эти поля являются открытыми, защищенными (или закрытыми для пакета, в зависимости от вашего соглашения о видимости JavaDoc), вы должны добавить подробности о том, как эти поля инициализируются, основываясь на поведении статическогоинициализатор.

Answer 4

Я бы сказал, что важные части этой документации следует перенести в документацию класса:

/**
 * Your text here.
 */
public class SomeClass {
   static {
      /* your static initalizer */
   }
}