Написание документирующих комментариев (Javadoc)

Сложность: easy Тема: CON

javadoc комментарии документация API

Контекст задачи

Комментарии служат для пояснения программного кода тем, кто его читает — будь то другой разработчик или вы сами через полгода. Javadoc — это стандарт документации в Java: специальные комментарии /** ... */, которые обрабатываются инструментом javadoc для создания HTML-документации API. Без комментариев код — это набор слов без контекста. С комментариями — это документированный, поддерживаемый продукт.

Формулировка

Напишите документирующие комментарии Javadoc для всех публичных классов, методов и полей модели данных вашего программного проекта. Сгенерируйте HTML-документацию с помощью инструмента javadoc и убедитесь, что она формируется без ошибок и предупреждений.

Ожидаемый результат

Javadoc-комментарии для каждого публичного класса, метода и значимого поля
Использование блочных тегов: @param, @return, @throws, @author, @version
Сгенерированная HTML-документация, открывающаяся в браузере
Отсутствие предупреждений (warnings) при генерации

Инструментарий

Методы и подходы:

Структура Javadoc-комментария: краткое описание + детализация + теги
Блочные теги: @param, @return, @throws, @see, @since, @deprecated
HTML-разметка внутри комментариев (например, <p>, <code>, <ul>)
Генерация документации через javadoc или Maven-плагин
Документирование пакетов (package-info.java)

Инструменты:

Язык: Java
Команда: javadoc -d docs -subpackages src
IDE: автогенерация Javadoc (IntelliJ: Code → Generate Javadoc)
Maven: плагин maven-javadoc-plugin

Навигатор

Javadoc — документация
Шпаргалка по Markdown — GitHub
Вопрос: Какой минимум информации нужен разработчику, чтобы использовать ваш метод, не читая его тело?
Пример:

/**
 * Класс, демонстрирующий применение документирующих комментариев.
 * <p>
 * Создан для методических указаний по курсовому проектированию.
 *
 * @author Minakova
 * @version 1.2
 */
public class SquareNum {

    /**
     * Этот метод возвращает квадрат значения параметра num.
     * Это описание состоит из нескольких строк. Число строк
     * не ограничивается.
     *
     * @param num Значение, которое требуется возвести в квадрат.
     * @return Квадрат числового значения параметра num.
     */
    public double square(double num) {
        return num * num;
    }

    /**
     * Этот метод получает значение, введенное пользователем.
     *
     * @return Введенное значение типа double.
     * @exception IOException Ошибка ввода.
     * @see IOException
     */
    public double getNumber() throws IOException {
        InputStreamReader isr = new InputStreamReader(System.in);
        BufferedReader inData = new BufferedReader(isr);
        String str = inData.readLine();
        return (new Double(str)).doubleValue();
    }
}

📝 Критерии оценки

Javadoc-комментарии написаны для всех публичных классов
Javadoc-комментарии написаны для всех публичных методов
Javadoc-комментарии написаны для всех публичных полей
Использованы теги: @param, @return, @throws, @author, @version
HTML-разметка в комментариях корректна (нет незакрытых тегов)
HTML-документация сгенерирована без ошибок и предупреждений
Сгенерированная HTML-документация корректно описывает назначение классов и методов