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

При кодировании на С# я всегда обнаружил, что тег remarks очень полезен для предоставления заметок о реализации класса или метода или для предоставления информации о теории того, что я реализую. Я использую Java, но я не могу найти подходящий тег JavaDoc для этого. Возможно, в Java вы выполняете это по-другому, знает ли кто-нибудь?

Ответ 1

Насколько я знаю, для примечаний или замечаний нет специального тега Javadoc. Как правило, первое предложение Javadoc должно содержать краткое описание поля class/method/. Затем следует полное описание. И если вы хотите включить какие-либо примечания, достаточно специального раздела с надписью "Примечание:".

/**
 * Brief description. Full description of the method, generally without
 * implementation details.
 * <p>
 * Note: Additional information, e.g. your implementation notes or remarks.
 * </p>
 * @param input description of the parameter
 * @return description of return value
 * 
 * @since version
 * @author name of the author
 */
public boolean doSomething(String input)
{
    // your code
}

Ответ 2

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

Ответ 3

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

/**
 * Does something.
 * <p>
 * <b>Implementation details:</b><br />
 * Blah blah blah...
 * </p>
 */
public void doSomething() {
    // ...
}

Ответ 4

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

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

    /**
     * Quark represents a quark.
     *
     * @note If you spin a quark, it will spin forever!
     */
    public class Quark {

    }

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

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

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