Этот быстрый урок охватывает Javadoc, полезный инструмент для создания документации из ваших исходных файлов Java. Этот урок является частью непрерывной серии учебных пособий для разработчиков, изучающих Java с целью разработки приложений для Android.
Что такое Javadoc?
Javadoc — это утилита, поставляемая с Java SDK, которая позволяет разработчикам создавать документацию кода из исходных файлов Java. Среды разработки, такие как Eclipse, имеют встроенную поддержку Javadoc и могут генерировать справочные материалы HTML с возможностью поиска из комментариев в стиле Javadoc. Фактически, ссылка на Android SDK является формой документации Javadoc.
Как работает Javadoc?
Документация Javadoc использует комбинацию обработки исходного кода (и проверки типов, параметров и т. Д.) И чтения специальных тегов комментариев, которые разработчик предоставляет в виде метаданных, связанных с разделом кода.
Комментарий в стиле Javadoc должен находиться перед кодом, с которым он связан. Например, комментарий Javadoc для класса должен быть чуть выше объявления класса, а комментарий для метода должен быть чуть выше объявления метода. Каждый комментарий должен начинаться с краткого описания, за которым следует опция более подробного описания. Затем вы можете включить ряд различных тегов метаданных, которые должны предоставляться в определенном порядке. Некоторые важные теги включают в себя:
- @author — кто написал этот код
- @version — когда это изменилось
- @param — опишите параметры метода
- @return — опишите возвращаемые значения метода
- @throws — опишите выданные исключения
- @see — ссылка на другие связанные элементы (например, «Смотрите также…»)
- @since — опишите, когда был представлен код (например, уровень API)
- @deprecated — опишите устаревший элемент и какую альтернативу использовать вместо
Вы также можете создавать свои собственные теги для использования в документации.
Создание комментариев в стиле Javadoc в Eclipse
Пока вы пишете код в Eclipse, вы можете сгенерировать комментарий в стиле Javadoc, выбрав элемент, который вы хотите прокомментировать (имя класса, имя метода и т. Д.) И нажав Alt-Shift-J (Cmd-Shift-J на Mac). Это создаст базовый комментарий в стиле Javadoc для вас, чтобы заполнить детали.
Простой Javadoc Класс Комментарии
Давайте посмотрим на пример. Вот простой комментарий Javadoc, который описывает класс:
/ ** * Активность по загрузке ресурсов макета * * Это действие используется для отображения различных ресурсов макета для учебника по дизайну пользовательского интерфейса. * * @author LED * @version 2010.1105 * @since 1.0 * / открытый класс LayoutActivity расширяет Activity {
Вот как это будет выглядеть при создании документации Javadoc:
Простой Javadoc Field Комментарии
Давайте посмотрим на пример. Вот простой комментарий Javadoc, который описывает поле в классе:
/ ** * Отладочный тег для использования записи отладочного вывода в LogCat * / приватная статическая final String DEBUG_TAG = "MyActivityDebugTag";
Вот как это будет выглядеть при создании документации Javadoc:
Простой Javadoc Метод Комментарии
Теперь давайте посмотрим на два примера комментариев метода. Вот простой комментарий Javadoc, который описывает метод в классе:
/ ** * Метод, который добавляет два целых числа вместе * * @param a Первое целое число, которое нужно добавить * @param b Второе целое число, чтобы добавить * @return Полученная сумма а и б * / public int addIntegers (int a, int b) { возврат (a + b); }
Теперь давайте посмотрим на метод, который возвращает void, но выдает исключение:
/ ** * Этот метод просто генерирует исключение, если входящий параметр a не является положительным числом, просто для удовольствия. * * @param a Выдавать или нет исключение * Исключения @ выбрасывает * / public void throwException (логическое shouldThrow) бросает Исключение { if (shouldThrow == true) { бросить новое исключение (); } }
Вот как это будет выглядеть при создании документации Javadoc для этих двух методов:
Создание документации Javadoc в Eclipse
Чтобы сгенерировать документацию по коду Javadoc в Eclipse, перейдите в меню «Проект» и выберите «Создать Javadoc…». Это запустит мастер, который позволит вам выбрать проекты для создания документации.
В этом мастере вы должны указать Eclipse на соответствующий инструмент командной строки javadoc.exe (вы найдете его в каталоге / bin вашего JDK). Вы также можете настроить некоторые параметры документации, например, задокументировать весь код или только видимые классы, члены и т. Д. Наконец, выберите место назначения для файлов документации.
Даже без создания файлов Javadoc Eclipse будет показывать документацию в стиле Javadoc при наведении указателя мыши на ваши методы и тому подобное, как показано на рисунке ниже.
Узнать больше о Javadoc
Вы можете узнать больше из ссылки на Javadoc на сайте Oracle . Существует также полезный Javadoc FAQ .
Вывод
В этом коротком уроке вы узнали о Javadoc, мощном инструменте, используемом разработчиками Java для тщательного документирования исходного кода в целях справки и обслуживания. Eclipse, среда разработки, используемая многими разработчиками Android, имеет встроенную поддержку Javadoc.
Об авторах
Разработчики мобильных приложений Лорен Дарси и Шейн Кондер являются соавторами нескольких книг по разработке Android: углубленная книга по программированию под названием « Разработка беспроводных приложений для Android» и « Разработка Android-приложений Sams TeachYourself за 24 часа» . Когда они не пишут, они тратят свое время на разработку мобильного программного обеспечения в своей компании и оказание консультационных услуг. С ними можно связаться по электронной почте [email protected] , через их блог на androidbook.blogspot.com и в Twitter @androidwireless .
Нужна дополнительная помощь в написании приложений для Android? Проверьте наши последние книги и ресурсы!
