Замечания по использованию в javadocs ⇐ JAVA

[Anonymous]

Если я хочу задокументировать, как следует использовать мой класс, следует ли мне поместить это в тело javadoc или в `@apiNote`? Если первое, то для чего второе?
У меня такое впечатление, что тело должно быть очень кратким, максимум одно или несколько предложений, описывающих, что это такое. Любые инструкции для пользователей класса лучше подходят для `@apiNote`.
Однако многие библиотеки помещают их в тело.
Что вы думаете?

Подробнее здесь: https://stackoverflow.com/questions/798 ... n-javadocs