Пример использования Javadoc в Java: синтаксис и форматирование
Быстрый ответ
/**
* Вычисляет произведение двух положительных целых чисел.
* Отличается высокой эффективностью, превышающей уровень энергии программиста после кофе. ☕
*
* @param x Первый множитель, отрицательные значения запрещены.
* @param y Второй множитель, также должен быть неотрицательным.
* @return Результат умножения x на y, готовый по мановению волшебной палочки.
* @throws IllegalArgumentException если хотя бы один из аргументов отрицателен —
* негативные значений здесь приниматься не будут!
*/
public int multiply(int x, int y) {
if (x < 0 || y < 0) {
throw new IllegalArgumentException("Оба множителя должны быть неотрицательными. Избегаем негатива!");
}
return x * y;
}
Выделяйтесь среди остальных в Javadoc: даёте обширное описание параметров, уточняйте проверки и ясно обозначьте условия исключений. Ваши пользователи будут вам благодарны!
Создание Javadoc: пошаговое руководство
Используйте активный залог
Активный залог обычно звучит яснее и непосредственнее:
- "Возвращает размер" вместо "Размер возвращен".
- "Генерирует IOException" вместо "Исключение генерируется".
Укажите информацию о потокобезопасности
Дайте знать пользователю, безопасно ли использование вашего компонента в многопоточной среде. Используйте термины "потокобезопасно" или "не потокобезопасно".
/**
* Потокобезопасный счетчик, готовый победить состояние гонки.
*/
public class ThreadSafeCounter {
// Реализация...
}
Действуйте с уважением к устаревшему коду
Укажите, почему код устарел, предложите альтернативы и поясните, как перейти на новый код. Эта информация пригодится всем.
/**
* @deprecated Устарел начиная с версии 3.2. Вместо него используйте {@link NewFeature},
* он работает быстрее и лучше, не утащит при этом ваш обед.
*/
@Deprecated
public class OldFeature {
// Реализация...
}
Визуализация
Сделайте Javadoc прозрачным и понятным. Пусть классы (деревья🌲) и методы (тропинки🌳) станут для вас надежными путеводителями:
🌲 Дерево классов: КорзинаЭкзотическихФруктов
/**
* 🗺️ Введение: "Представляем вашему вниманию КорзинаЭкзотическихФруктов – свежайший коктейль ароматов, ведущий от востока до дуриана — самого пахучего фрукта."
* 🍍 @param tropicalFruits – массив сочных и изысканных экзотических фруктов.
* 🌟 @return Отсортированная корзина экзотических вкусовых ощущений.
* 🚫 @throws FruitException если фрукт не свеж или не экзотический.
*/
public Basket collectRarest(TropicalFruit[] tropicalFruits)
🌳 Путь: collectRarest()
– Краткое описание: ✍️ "Сборник исключительно редких фруктов для истинных гурманов."
– Параметры: 🍍 "Царство экзотики: дуриан, питайя и многое другое. Обычные бананы — пройдём мимо."
– Возвращаемое значение: 🌟 "Избранные фрукты из самых отдалённых уголков тропиков в одной корзине."
– Риски: 🚫 "Фальсификат здесь не пройдёт. Мы гарантируем только настоящие экзотические изыски."
Совет дня: "Четкость Javadoc — ваш билет в мир кода. Помогите коллегам разобраться!"
Javadoc: ключи к успеху
Искусство простоты
Class Collections
JDK является образцом простоты и ясности. Уважайте время своих коллег, и они ответят вам взаимностью.
Используйте примеры кода
Пустые слова не внушают доверия, а вот "увидеть однажды" значит "поверить". В Apache Commons Lang представлены обширные и практичные примеры использования.
/**
* Переводит первую букву строки в верхний регистр.
*
* <pre>
* StringUtils.capitalize(null) = null
* StringUtils.capitalize("") = "" // Пустота – тоже сигнал.
* StringUtils.capitalize("cat") = "Cat" // "мяу" стало "МЯУ"!
* StringUtils.capitalize("cAt") = "CAt"
* </pre>
*
* @param str исходная строка, может быть null
* @return строка со строкой, начинающейся с заглавной буквы, или {@code null}, если исходная строка была null
*/
public static String capitalize(String str) {
// Здесь код...
}
Связывайте элементы друг с другом – используйте ссылки на связанный код
Помогайте читателям навигироваться по вашим компонентам с помощью {@link ClassName#methodName}
. Это особенно полезно при работе с большой библиотекой.
Полезные материалы
- Code Conventions for the Java Programming Language: 5. Comments — Правила по составлению документации Java-кода от Oracle.
- javadoc — Руководство по Javadoc от Oracle.
- Apache Commons Lang 3.11 API — Описание использования Javadoc с обстоятельными примерами.
- GitHub – jbloch/effective-java-3e-source-code — Примеры из книги "Effective Java".
- How to Write Doc Comments for the Javadoc Tool — Обзор создания комментариев для Javadoc от Oracle.
- Java – Documentation Comments — Введение в работу с Javadoc на примерах.