JavaDoc: где добавлять заметки/пояснения в документацию?

С выходом итерации 8 языка программирования Java разработчики наконец получили три дополнительных тега, которые они могут использовать в документации к своему коду. Это теги @apiNote, @implSpec и @implNote, которые должны удовлетворить ваши потребности. Для более подробного обсуждения вы можете ознакомиться с этой статьей: http://blog.codefx.org/java/new-javadoc-tags/.

На русском языке ответ на вопрос может выглядеть следующим образом:

Насколько я знаю, для добавления заметок или комментариев в Javadoc нет специального тега. Обычно первое предложение Javadoc должно содержать краткое описание класса, метода или поля. Далее следует полное описание. Если вы хотите включить какие-либо заметки, достаточно добавить специализированный абзац с префиксом "Замечание:".

Пример:

/**
 * Краткое описание. Полное описание метода, обычно без
 * деталей реализации.
 * <p>
 * Замечание: Дополнительная информация, например, ваши заметки или комментарии к реализации.
 * </p>
 * @param input описание параметра
 * @return описание возвращаемого значения
 * 
 * @since версия
 * @author имя автора
 */
public boolean doSomething(String input)
{
    // ваш код
}

Таким образом, вы можете организовать документацию в Javadoc, добавляя необходимые примечания для лучшего понимания вашего кода.

Вы также можете создавать свои собственные пользовательские теги.

Вот пример комментария в формате javadoc, который включает пользовательский тег "@note":

    /**
     * Кварк представляет кварк.
     *
     * @note Если вы заставите кварк вращаться, он будет вращаться вечно!
     */
    public class Quark {

    }

Чтобы сгенерировать javadocs для приведенного выше кода, выполните команду javadoc следующим образом:

javadoc -tag note:a:"Примечание:" Quark.java

Источник: http://www.developer.com/java/other/article.php/3085991/Javadoc-Programming.htm

Если вы считаете, что детали реализации достаточно интересны, чтобы их включить в Javadoc, просто добавьте их в виде абзаца в комментарий Javadoc:

/**
 * Выполняет какое-то действие.
 * <p>
 * <b>Детали реализации:</b><br />
 * Тут написано всякое...
 * </p>
 */
public void doSomething() {
    // ...
}