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

Question

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

Answer 1

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

/**
 * 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
}

Answer 2

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

Answer 3

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

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

Answer 4

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

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

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

    }

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

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

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