Javadoc в Java

Документируйте метод особым комментарием, чтобы читатели и инструменты видели, что он принимает и что возвращает. В Yard.java напишите метод add, который принимает int x и int y и возвращает их сумму. Поставьте блок /** */ прямо над add. Внутри блока опишите работу одним коротким предложением, затем пометьте каждый параметр через @param и результат через @return. В main напечатайте add(10, 2). Скомпилируйте через javac Yard.java и запустите java Yard. Экран должен показать 12. Правила именования оставьте для следующей страницы — этот урок про форму комментария документации, а не про выбор имён.

Поставьте /** над методом

Страница debugging печатала значения, чтобы найти неверную сумму. Эта страница пишет комментарий документации над чистым методом. Откройте Yard.java. Держите имя public-класса Yard. Удалите оставшиеся метки println отладки, если они хоронят историю документации, оставшиеся демо equals / ==, оставшиеся файлы horn у Machine и любой клавиатурный Scanner. Программа не должна ждать ввода. Строка import для этой демо не нужна.
Внутри Yard держите маленький метод и короткий main. Блок документации должен сидеть сразу над методом, который описывает. Пустая строка между закрывающим */ и строкой метода допустима. Не прячьте блок внутри main. Не ставьте блок под телом метода.
Открытие комментария пишите с двумя звёздочками после слэша:
/**
Затем напишите одно простое предложение о том, что делает add. Затем напишите теги. Закройте так:
*/
Сам метод остаётся обычным Java:
static int add(int x, int y) {
return x + y;
}
Javadoc не меняет работу return. Он говорит читателю, что метод обещает, до того как тот прочитает каждую строку тела.

Из папки, где лежит Yard.java, запустите javac Yard.java. Когда скобки, фигурные скобки и точки с запятой совпадают, javac не пишет собственной строки. Затем запустите java Yard — не java Yard.java. Уберите окончание .java из команды запуска. Держите один public-класс в файле, чтобы имя совпадало с Yard.
Экран показывает 12. Пройдите запуск один раз. Java начинает с Yard.main. Вызов add(10, 2) входит в метод с x, держащим десять, и y, держащим два. Строка return отдаёт двенадцать. System.out.println пишет это число. Блок Javadoc сам по себе не печатается. Блок — для читателей и инструментов документации. Доказательство для новичка на этой странице всё ещё верный запуск после ясного комментария.
Читайте блок комментария, глядя на сигнатуру метода. Предложение Adds two numbers. совпадает с работой return x + y;. Строка @param x first number называет первый параметр. Строка @param y second number называет второй параметр. Строка @return the sum of x and y называет результат. Держите написание тегов точным: @param и @return используют знак @ и латинские буквы.
Если вы всё ещё видите x=10 и y=2, затем 8 из файла debugging, переключитесь на учебный файл Javadoc и снова запустите java Yard. Если над методом вы пишете только // Adds two numbers., вы написали обычный строчный комментарий, а не блок Javadoc. Держите форму с двумя звёздочками /**, чтобы блок был документацией, а не однострочной заметкой.
Произнесите правило вслух, глядя на экран: документируйте над методом, пометьте параметры, пометьте возврат, затем скомпилируйте и запустите, чтобы доказать, что метод всё ещё работает. Не изобретайте длинные лекции об именовании на этой странице. Именование ждёт следующего урока.

Прочитайте карту тегов

Короткая таблица держит три части, которые вы набрали в комментарии. Открытие /** */ отмечает блок документации. @param описывает одно имя параметра. @return описывает значение, которое метод отдаёт. Держите имя метода add и вызов add(10, 2), чтобы экран оставался одним ясным числом.
Таблица — короткая карта этой страницы. Сначала вы ставите блок. Затем помечаете входы и выход. Затем проверяете через javac и java Yard. Не гадайте, что любой стиль комментария — это Javadoc. Не удаляйте блок, пока не знаете, что программа всё ещё печатает 12.

Держите таблицу рядом с учебным файлом, пока правите. Укажите на @param x в файле, затем на int x в сигнатуре. Укажите на @param y, затем на int y. Укажите на @return, затем на строку return. Эта игра сопоставления — вся начинающая идея за один проход. Инструменты, которые читают Javadoc, ищут эти теги. Человеческие читатели используют ту же карту, когда тело метода позже вырастет.
Если рядом ещё лежат демо debugging, оставьте их как историю. Для этого урока запускайте учебный файл Javadoc, чтобы экран показывал 12 из add, а не строки с метками x= из охоты за багом. Если javac жалуется на дублирующие public-классы, держите public только у Yard.

Обычный // — это не Javadoc

Строка, которая начинается с //, — заметка для того, кто читает файл. Она полезна, и этот курс уже использовал строчные комментарии раньше. Это не форма блока документации, которую учит эта страница. Javadoc для метода начинается с /** и заканчивается */. Теги @param и @return сидят внутри этого блока.
Если вы ставите обычную строку под методом после других операторов, эта строка не является документацией метода. Блок документации должен быть комментарием, прикреплённым над методом. Держите блок плотно к add. Держите main свободным от театральной фальшивой документации. Вызов в main остаётся обычной печатью возвращённой суммы.
Когда комментарий неверен, а тело метода верно, javac всё ещё может пройти успешно, и java Yard всё ещё может напечатать 12. Поэтому эта страница просит читать комментарий и сигнатуру вместе, а не только экран. Экран доказывает математику. Комментарий доказывает, что вы пометили контракт.

Сравнение с печатями debugging

На странице debugging println отвечал, каковы ваши числа на самом деле, когда сумма выглядела неверно. На этой странице Javadoc отвечает, что add обещает, до того как читатель углубится в тело. Вы по-прежнему компилируете Yard.java и запускаете java Yard. Новые токены — /**, @param и @return над методом.
Debugging использовал обычный вывод как фонарик. Javadoc использует структурированный комментарий как ярлык на двери метода. Когда ярлык совпадает с параметрами и возвратом, читатели меньше гадают. Когда ярлык отсутствует, программа всё ещё может запуститься — привычка документации всё ещё отсутствует.
Если ещё открыт оставшийся файл debugging, вы можете увидеть x=10, y=2 и старую сумму. Переключитесь на файл Javadoc, чтобы main печатал add(10, 2) и метод нёс блок документации. Держите лекции о стиле именования вне этой страницы. Держите клавиатурный ввод вне этой страницы.

Перед именованием

Вы можете поставить /** */ над add, пометить @param x, пометить @param y, пометить @return и всё ещё увидеть 12 после java Yard. Скомпилируйте Yard.java и запустите java Yard для сохранённой демо. Комментарий сказал читателям контракт. Следующая страница — именование, где вы выбираете ясные имена для того, что пишете.
Держите задокументированную демо add для ясной пары комментарий-плюс-запуск. Держите файлы debugging вне этой страницы, когда практикуете документацию. Держите файлы naming вне этой страницы до того урока. Эти три привычки — контрольная точка перед переходом. Когда теги совпадают с сигнатурой и экран показывает 12, Javadoc сделал своё дело для этого урока, и вы готовы к следующей теме об именовании.
Ещё один проход по папке: один public Yard, один задокументированный add, одна печать в main, без ожидания клавиатуры, без принудительных правил именования. Ещё раз запустите javac Yard.java и java Yard на демо, которую держите открытой. Если экран всё ещё показывает 12 и комментарий всё ещё сидит над add с @param и @return, форма документации крепка, и курс может перейти к именованию на следующей странице. Предпочитайте один ясный блок документации на одном методе, чтобы каждое чтение учило ту же карту.