Автоматическое документирование кода Java с помощью Javadoc

Если вы занимаетесь каким-либо программированием, вы прекрасно знаете, что одной из самых утомительных задач является документирование вашего кода. Независимо от того, считаете ли вы это слегка раздражающим или вызываете у вас абсолютный страх, документация по коду необходима. Другим нужно понять, как работает ваш код, и вы даже можете стать одним из них, если прочтете его позже!

Java удобно предоставляет встроенное решение проблемы: Javadoc.

Javadoc может помочь вам автоматически документировать код

Надеюсь, вы уже подписаны хорошие практики кодирования и включите пояснительные комментарии в свой код. Хотя этот тип комментариев в коде, безусловно, полезен, на самом деле он не дает ничего сравнимого с руководством.

Конечно, другой программист может просмотреть ваш код и прочитать о конкретных классах, методах и функциях, которые находятся перед ним. Однако очень сложно получить хороший обзор всего кода или найти функции, которые могут быть полезны, когда вы не знаете об их существовании. Javadoc призван решить эту проблему.

Javadoc автоматически сгенерирует подробное и удобное для чтения руководство в формате HTML для всего вашего кода. Лучше всего то, что он делает это с помощью комментариев к коду, которые вы, вероятно, уже написали.

Что такое Javadoc и как он работает?

Javadoc — это отдельная программа, которая поставляется в комплекте с выпусками Oracle Java Development Kit (JDK). На самом деле, вы не можете скачать его отдельно. Когда вы загружаете и установить одну из версий Oracle JDK, он также установит Javadoc.

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

Короче говоря, Javadoc позволяет вам одновременно писать код и документацию к нему. Это упрощает рабочий процесс и позволяет более эффективно использовать свое время.

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

Комментарии Javadoc должны непосредственно предшествовать объявлению класса, поля, конструктора или метода. Сам комментарий должен:

• Начните с трех символов /**.
• Ставьте звездочку в начале каждой новой строки.
• Закрыть двумя символами */.

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

Вот пример, иллюстрирующий простые комментарии Javadoc, описывающие функцию, которая получает изображение по URL-адресу и выводит его на экран. Комментарий непосредственно предшествует функции и описывает, что она делает. В этом блоке комментариев также используются три тега для конкретных разделов: @параметр, @возвращаться, а также @видеть.

/**
* Возвращает объект Image, который затем можно нарисовать на экране.
* Аргумент URL должен указывать абсолютный {@ссылка на сайт URL}. Название
* аргумент — это спецификатор, относящийся к аргументу URL.
* 

* Этот метод всегда возвращает результат немедленно, независимо от того,
* изображение есть. Когда это апплет пытается нарисовать изображение на
* экран, данные будут загружены. Графические примитивы
* рисующее изображение будет постепенно рисоваться на экране.
*
* @параметр url абсолютный URL-адрес, указывающий базовое местоположение изображения
* @параметр укажите местоположение изображения относительно аргумента URL
* @возвращаться изображение по указанному URL
* @видеть Изображение
*/
публичный Изображение получить изображение(URL-адрес, имя строки){
пытаться {
возвращаться получить изображение (новый URL(URL, имя));
 } ловить (MalformedURLException e) {
возвращатьсянулевой;
 }
}

Когда Javadoc обрабатывает приведенный выше код, он создает веб-страницу, подобную следующей:

Браузер отображает вывод Javadoc почти так же, как любой HTML-документ. Javadoc игнорирует лишние пробелы и разрывы строк, если вы не используете теги HTML для создания этого пробела.

Теги @, используемые в конце комментария, генерируют Параметры, Возвращает, а также Смотрите также разделы, которые вы видите.

Вы должны следовать @параметр тег с именем параметра, пробелом и его описанием. В случае выше есть два параметра: URL а также имя. Обратите внимание, что оба отображаются под одним и тем же заголовком «Параметры» в выходных данных документации. Вы можете перечислить столько параметров, сколько необходимо для описываемой функции или метода.

@возвращаться тег документирует значение, которое функция возвращает, если вообще возвращает. Это может быть простое описание из одного слова или много предложений, в зависимости от обстоятельств.

@видеть tag позволяет вам помечать другие функции, которые связаны или имеют отношение к делу. В этом случае тег @see относится к другой функции, называемой просто Image. Обратите внимание, что ссылки, сделанные с помощью этого тега, являются интерактивными ссылками, позволяющими читателю перейти к указанному элементу в конечном HTML-коде.

Доступно больше тегов, таких как @version, @author, @exception и другие. При правильном использовании теги помогают связать элементы друг с другом и позволяют легко перемещаться по документации.

Запуск Javadoc в исходном коде

Вы вызываете Javadoc в командной строке. Вы можете запускать его для отдельных файлов, целых каталогов, пакетов Java или списка отдельных файлов. По умолчанию Javadoc создает файлы документации HTML в каталоге, в котором вы вводите команду. Чтобы получить справку по конкретным доступным командам, просто введите:

javadoc --помощь

Чтобы узнать, что именно может сделать Javadoc более подробно, ознакомьтесь с официальной документацией от Оракул. Чтобы создать быстрый набор документации по одному файлу или каталогу, вы можете ввести javadoc в командной строке, за которым следует имя файла или подстановочный знак.

Javadoc ~/code/имя файла.java
Javadoc ~/code/*.Ява

Выше приведен список файлов и каталогов, созданных Javadoc. Как видите, их довольно много. По этой причине вы должны быть уверены, что вы не находитесь в том же каталоге, что и ваш исходный код, когда вы запускаете программу. Это может создать настоящий беспорядок.

Чтобы просмотреть только что созданные документы, просто откройте index.html файл в предпочитаемом вами браузере. Вы получите страницу, подобную следующей:

Это документация для одного короткого класса Java для демонстрации вывода. Заголовок показывает имя класса, а также включенные в него методы. Прокрутка вниз показывает более подробные определения каждого из методов класса.

Как видите, для любого типа Java-проекта, особенно крупного, состоящего из многих тысяч строк кода, этот тип документации бесценен. Было бы непросто узнать о большой кодовой базе, прочитав ее исходный код. Страницы Javadoc значительно ускоряют и упрощают этот процесс.

Javadoc может помочь вам организовать код Java и всю соответствующую документацию и упростить их использование. Делаете ли вы это для себя забывчивого будущего или для облегчения работы большой команды, Javadoc — это мощный инструмент, который может изменить то, как вы пишете код Java и взаимодействуете с ним. проекты.

8 лучших блогов Java для программистов

Читать дальше