Последнее обновление 05.01.2023 — Василий Иванов
Если вы занимаетесь каким-либо программированием, вы хорошо знаете, что одной из самых утомительных задач является документирование вашего кода. Независимо от того, находите ли вы это слегка раздражающим или вызываете у вас абсолютный страх, документация по коду необходима. Другим нужно понять, как работает ваш код, и вы даже можете стать одним из них, если прочтете его позже!
Java удобно предоставляет встроенное решение проблемы: Javadoc.
Javadoc может помочь вам автоматически документировать код
Надеюсь, вы уже следуете хорошим практикам написания кода и включаете в свой код пояснительные комментарии. Хотя этот тип комментариев в коде, безусловно, полезен, на самом деле он не дает ничего сравнимого с руководством.
Конечно, другой программист может просмотреть ваш код и прочитать о конкретных классах, методах и функциях, которые находятся перед ним. Однако очень сложно получить хороший обзор всего кода или найти функции, которые могут быть полезны, когда вы не знаете об их существовании. Javadoc призван решить эту проблему.
Javadoc автоматически сгенерирует подробное и удобное для чтения руководство в формате HTML для всего вашего кода. Лучше всего то, что он делает это с помощью комментариев к коду, которые вы, вероятно, уже написали.
Что такое Javadoc и как он работает?
Javadoc — это отдельная программа, которая поставляется вместе с выпусками Oracle Java Development Kit (JDK). На самом деле, вы не можете скачать его отдельно. Когда вы загружаете и устанавливаете одну из версий Oracle JDK, она также устанавливает Javadoc.
Когда вы запускаете его, Javadoc генерирует HTML-документацию из специально отформатированных комментариев в вашем исходном коде Java. Этот процесс создает более полезную и удобочитаемую документацию, а также поощряет передовой опыт.
Короче говоря, Javadoc позволяет вам одновременно писать код и документацию к нему. Это упрощает рабочий процесс и позволяет более эффективно использовать свое время.
Как создавать комментарии, совместимые с Javadoc
Javadoc работает, анализируя специально отформатированные комментарии в вашем коде и преобразовывая их в вывод HTML. Единственное изменение, которое вам действительно нужно сделать, это включить в комментарии определенные строки. Они сообщают Javadoc, что вы хотите включить в окончательную документацию.
Комментарии Javadoc должны непосредственно предшествовать объявлению класса, поля, конструктора или метода. Сам комментарий должен:
- Начните с трех символов /**.
- Ставьте звездочку в начале каждой новой строки.
- Закройте двумя символами */.
В комментариях вы можете включить HTML в окончательный вывод и включить теги, которые будут генерировать ссылки на соответствующие части вашей кодовой базы. Вы даже можете использовать такие вещи, как теги изображений HTML, чтобы включить изображения в окончательную документацию. Как только вы привыкнете к формату и доступным тегам, писать такие комментарии станет проще простого.
Вот пример, иллюстрирующий простые комментарии Javadoc, описывающие функцию, которая получает изображение по URL-адресу и выводит его на экран. Комментарий непосредственно предшествует функции и описывает, что она делает. В этом блоке комментариев также используются три тега для конкретных разделов: @param, @return и @see.
/**
* Returns an Image object that can then be painted on the screen.
* The url argument must specify an absolute <a href="#{@link}">{@link URL}</a>. The name
* argument is a specifier that is relative to the url argument.
* <p>
* This method always returns immediately, whether or not the
* image exists. When this applet attempts to draw the image on
* the screen, the data will be loaded. The graphics primitives
* that draw the image will incrementally paint on the screen.
*
* @param url an absolute URL giving the base location of the image
* @param name the location of the image, relative to the url argument
* @return the image at the specified URL
* @see Image
*/
public Image getImage(URL url, String name) {
try {
return getImage(new URL(url, name));
} catch (MalformedURLException e) {
return null;
}
}
Когда Javadoc обрабатывает приведенный выше код, он создает веб-страницу, подобную следующей:
Браузер отображает вывод Javadoc почти так же, как любой HTML-документ. Javadoc игнорирует лишние пробелы и разрывы строк, если вы не используете теги HTML для создания этого пробела.
Используйте теги Javadoc для специальных сведений и ссылок
Теги @, используемые в конце комментария, создают разделы «Параметры», «Возвраты» и «См. также», которые вы видите.
Вы должны следовать за тегом @param с именем параметра, пробелом и его описанием. В случае выше есть два параметра: URL и имя. Обратите внимание, что оба отображаются под одним и тем же заголовком «Параметры» в выходных данных документации. Вы можете перечислить столько параметров, сколько необходимо для описываемой функции или метода.
Тег @return документирует значение, которое функция возвращает, если вообще возвращает. Это может быть простое описание из одного слова или много предложений, в зависимости от обстоятельств.
Тег @see позволяет вам помечать другие связанные или релевантные функции. В этом случае тег @see относится к другой функции, называемой просто Image. Обратите внимание, что ссылки, сделанные с помощью этого тега, являются интерактивными ссылками, позволяющими читателю перейти к указанному элементу в конечном HTML-коде.
Доступно больше тегов, таких как @version, @author, @exception и другие. При правильном использовании теги помогают связать элементы друг с другом и позволяют легко перемещаться по документации.
Запуск Javadoc в исходном коде
Вы вызываете Javadoc в командной строке. Вы можете запускать его для отдельных файлов, целых каталогов, пакетов Java или списка отдельных файлов. По умолчанию Javadoc создает файлы документации HTML в каталоге, в котором вы вводите команду. Чтобы получить справку по конкретным доступным командам, просто введите:
javadoc --help
Чтобы более подробно узнать, что может сделать Javadoc, ознакомьтесь с официальной документацией Oracle. Чтобы создать быстрый набор документации для одного файла или каталога, вы можете ввести javadoc в командной строке, а затем имя файла или подстановочный знак.
javadoc ~/code/filename.java
javadoc ~/code/*.java
Выше приведен список файлов и каталогов, созданных Javadoc. Как видите, их довольно много. По этой причине вы должны быть уверены, что вы не находитесь в том же каталоге, что и ваш исходный код, когда вы запускаете программу. Это может создать настоящий беспорядок.
Чтобы просмотреть только что созданные документы, просто откройте файл index.html в предпочитаемом вами браузере. Вы получите страницу, подобную следующей:
Это документация для одного короткого класса Java для демонстрации вывода. Заголовок показывает имя класса, а также включенные в него методы. Прокрутка вниз показывает более подробные определения каждого из методов класса.
Как видите, для любого типа Java-проекта, особенно крупного, состоящего из многих тысяч строк кода, этот тип документации бесценен. Было бы непросто узнать о большой кодовой базе, прочитав ее исходный код. Страницы Javadoc значительно ускоряют и упрощают этот процесс.
Никогда больше не ищите комментарии к коду
Javadoc может помочь вам организовать код Java и всю соответствующую документацию и упростить их использование. Делаете ли вы это для своего забывчивого будущего или для облегчения работы большой команды, Javadoc — это мощный инструмент, который может изменить то, как вы пишете и взаимодействуете с вашими проектами кодирования Java.
