Java api documentation на русском
Документирование javadoc
При документировании приложения необходима также поддержка документации программы. Если документация и код разделены, то непроизвольно создаются сложности, связанные с необходимостью внесения изменений в соответствующие разделы сопроводительной документации при изменении программного кода.
Как правило, все существующие среды разработки IDE приложений Java предлагают решение по связыванию кода с документацией в процессе разработки с использованием javadoc. Для этого необходимо соответствующим образом написать комментарий к коду, т.е. документировать. Java комментарии необходимы как для комментирования программы, так и для составления или оформления документации.
Разработан специальный синтаксис для оформления документации в виде комментариев и инструмент для создания из комментариев документации. Этим инструментом является javadoc, который обрабатывая файл с исходным текстом программы, выделяет помеченную документацию из комментариев и связывает с именами соответствующих классов, методов и полей. Таким образом, при минимальных усилиях создания комментариев к коду, можно получить хорошую документацию к программе.
javadoc — это генератор документации в HTML-формате из комментариев исходного кода Java и определяет стандарт для документирования классов Java. Для создания доклетов и тэглетов, которые позволяют программисту анализировать структуру Java-приложения, javadoc также предоставляет API. В каждом случае комментарий должен находиться перед документируемым элементом.
При написании комментариев к кодам Java используют три типа комментариев :
С помощью утилиты javadoc, входящей в состав JDK, комментарий документации можно извлекать и помещать в НТМL файл. Утилита javadoc позволяет вставлять HTML тэги и использовать специальные ярлыки (дескрипторы) документирования. НТМL тэги заголовков не используют, чтобы не нарушать стиль файла, сформированного утилитой.
Дескрипторы javadoc, начинающиеся со знака @, называются автономными и должны помещаться с начала строки комментария (лидирующий символ * игнорируется). Дескрипторы, начинающиеся с фигурной скобки, например , называются встроенными и могут применяться внутри описания.
Комментарии документации применяют для документирования классов, интерфейсов, полей (переменных), конструкторов и методов. В каждом случае комментарий должен находиться перед документируемым элементом.
javadoc дескрипторы : @author, @version, @since, @see, @param, @return
| Дескриптор | Применение | Описание |
|---|---|---|
| @author | Класс, интерфейс | Автор |
| @version | Класс, интерфейс | Версия. Не более одного дескриптора на класс |
| @since | Класс, интерфейс, поле, метод | Указывает, с какой версии доступно |
| @see | Класс, интерфейс, поле, метод | Ссылка на другое место в документации |
| @param | Метод | Входной параметр метода |
| @return | Метод | Описание возвращаемого значения |
| @exception имя_класса описание | Метод | Описание исключения, которое может быть послано из метода |
| @throws имя_класса описание | Метод | Описание исключения, которое может быть послано из метода |
| @deprecated | Класс, интерфейс, поле, метод | Описание устаревших блоков кода |
| Класс, интерфейс, поле, метод | Ссылка | |
| Статичное поле | Описание значения переменной |
Форма документирования кода
Документирование класса, метода или переменной начинается с комбинации символов /** , после которого следует тело комментариев; заканчивается комбинацией символов */.
В тело комментариев можно вставлять различные дескрипторы. Каждый дескриптор, начинающийся с символа ‘@’ должен стоять первым в строке. Несколько дескрипторов одного и того же типа необходимо группировать вместе. Встроенные дескрипторы (начинаются с фигурной скобки) можно помещать внутри любого описания.
Для документирования кода можно использовать HTML теги. При использовании ссылочных дескрипторов @see и @link нужно сначала указать имя класса и после символа «#» его метод или поле.
Среда разработки IDE, как правило, помогает программисту «подсветкой» встроенной документации. На следующих рисунках приведены скриншоты всплывающих окон IDE Eclipse.
Утилита javadoc в качестве входных данных принимает файл с исходным кодом программы, для которого генерируется НТМL файл. Документация для каждого класса содержится в отдельном НТМL файле. Кроме этого, создается дерево индексов и иерархии. Могут быть сгенерированы и другие НТМL файлы.
Сценарии ant и javadoc
Для создания документации можно использовать ant.
Пример сценария (задания) ant для формирования документации к приложению MyProject :
Подробная информация формирования документации представлена на странице Javadoc/Javadoc2
Начинающим Java программистам
Программирую на Java вот уже 7 лет. Но на работе часто приходится обучать новое поколение. В связи с этим и решил сделать некоторую шпаргалку, которая, надеюсь, пригодится и для хабрчан. Если кто-то может помочь дополнить чем-то информацию из этой статьи, то пишите! Итак:
Основные ресурсы для начального обучения
Основные Java пакеты
Ниже приведён список Java пакетов, в которых программист должен свободно ориентироваться. Знакомиться с ними рекомендуется как по JavaDoc’ам, так и с помощью www.exampledepot.com. Все пакеты выстроены в рекомендуемом порядке для изучения. Итак:
- java.lang — основа основ. Каждый класс в этом пакете нуждается в отдельном внимании.
- java.io — ни одна программа не может обойтись без операций с вводом-выводом.
- java.util — пакет в основном содержит все необходимое для работы с коллекциями: Collection, Enumeration, Set, List, Map и т.д. и т.п.
- java.net — содержит основные классы для работы с сетью.
- java.text — все необходимое для форматирования текста
- java.lang.reflect — Java не была бы Java’ой если бы не Reflection. Reflection стирает грань между данными и кодом.
- javax.sql — все необходимое по работе с базами данных
- javax.xml.*, org.w3c.dom.*, org.xml.sax.* — без этих пакетов работа с XML просто немыслима
Ресурсы для расширения кругозора
- onjava.com — рано или поздно все новости мира Java попадают сюда
- www.javaspecialists.eu — ресурс полезен как новичкам, так и продвинутым программистам, так как содержит много статей о тонкостях работы с Java.
- www.theserverside.com — рекомендуется подписаться на RSS, так как часто проскакивают весьма интересные вещи по Java.
Java Библитеки, которые должны знать все
Java не заканчивается знаниями лишь о возможностях JSDK. Чтобы чувствовать себя комфортно необходимо знать еще десятка два сторонних библиотек, используемых Java программистами повсеместно. Итак, начнем с основных:
- Commons Lang — то что «забыли» включить в JDK
- Commons Math — отличное дополнение для java.math
- Commons Logging — логирование должно быть грамотным. За System.out.println для вывода логов начинающим программистам уже через неделю обучения следует отрубать руки.
- Commons Net — логическое продолжение для пакета java.net. Множество классов для работы с основными сетевыми протоколами.
- Commons VFS — отличная библиотека для абстрагирования от способа хранения файла. Позволяет достаточно обобщено иметь доступ до файлов по FTP, SFTP, WEBDAV, (G)ZIP и т.д.
- Commons IO — работа с вводом-выводом часто получается весьма муторной, но с этой библиотекой все становится несколько веселее.
- HttpClient — библиотека по работе с http ресурсами.
- JUnit — любой код, должен сопровождаться тестированием. Для автоматизации тестирования и предназначена эта библиотека.
На этом пока все. Если подобные шпаргалки по Java вам интересны, то могу так же выложить свою коллекцию «простейших» задач по Java, которые ориентированы, на то, чтобы быстро освоить основные пакеты Java.
Документирование javadoc
При документировании приложения необходима также поддержка документации программы. Если документация и код разделены, то непроизвольно создаются сложности, связанные с необходимостью внесения изменений в соответствующие разделы сопроводительной документации при изменении программного кода.
Как правило, все существующие среды разработки IDE приложений Java предлагают решение по связыванию кода с документацией в процессе разработки с использованием javadoc. Для этого необходимо соответствующим образом написать комментарий к коду, т.е. документировать. Java комментарии необходимы как для комментирования программы, так и для составления или оформления документации.
Разработан специальный синтаксис для оформления документации в виде комментариев и инструмент для создания из комментариев документации. Этим инструментом является javadoc, который обрабатывая файл с исходным текстом программы, выделяет помеченную документацию из комментариев и связывает с именами соответствующих классов, методов и полей. Таким образом, при минимальных усилиях создания комментариев к коду, можно получить хорошую документацию к программе.
javadoc — это генератор документации в HTML-формате из комментариев исходного кода Java и определяет стандарт для документирования классов Java. Для создания доклетов и тэглетов, которые позволяют программисту анализировать структуру Java-приложения, javadoc также предоставляет API. В каждом случае комментарий должен находиться перед документируемым элементом.
При написании комментариев к кодам Java используют три типа комментариев :
С помощью утилиты javadoc, входящей в состав JDK, комментарий документации можно извлекать и помещать в НТМL файл. Утилита javadoc позволяет вставлять HTML тэги и использовать специальные ярлыки (дескрипторы) документирования. НТМL тэги заголовков не используют, чтобы не нарушать стиль файла, сформированного утилитой.
Дескрипторы javadoc, начинающиеся со знака @, называются автономными и должны помещаться с начала строки комментария (лидирующий символ * игнорируется). Дескрипторы, начинающиеся с фигурной скобки, например , называются встроенными и могут применяться внутри описания.
Комментарии документации применяют для документирования классов, интерфейсов, полей (переменных), конструкторов и методов. В каждом случае комментарий должен находиться перед документируемым элементом.
javadoc дескрипторы : @author, @version, @since, @see, @param, @return
| Дескриптор | Применение | Описание |
|---|---|---|
| @author | Класс, интерфейс | Автор |
| @version | Класс, интерфейс | Версия. Не более одного дескриптора на класс |
| @since | Класс, интерфейс, поле, метод | Указывает, с какой версии доступно |
| @see | Класс, интерфейс, поле, метод | Ссылка на другое место в документации |
| @param | Метод | Входной параметр метода |
| @return | Метод | Описание возвращаемого значения |
| @exception имя_класса описание | Метод | Описание исключения, которое может быть послано из метода |
| @throws имя_класса описание | Метод | Описание исключения, которое может быть послано из метода |
| @deprecated | Класс, интерфейс, поле, метод | Описание устаревших блоков кода |
| Класс, интерфейс, поле, метод | Ссылка | |
| Статичное поле | Описание значения переменной |
Форма документирования кода
Документирование класса, метода или переменной начинается с комбинации символов /** , после которого следует тело комментариев; заканчивается комбинацией символов */.
В тело комментариев можно вставлять различные дескрипторы. Каждый дескриптор, начинающийся с символа ‘@’ должен стоять первым в строке. Несколько дескрипторов одного и того же типа необходимо группировать вместе. Встроенные дескрипторы (начинаются с фигурной скобки) можно помещать внутри любого описания.
Для документирования кода можно использовать HTML теги. При использовании ссылочных дескрипторов @see и @link нужно сначала указать имя класса и после символа «#» его метод или поле.
Среда разработки IDE, как правило, помогает программисту «подсветкой» встроенной документации. На следующих рисунках приведены скриншоты всплывающих окон IDE Eclipse.
Утилита javadoc в качестве входных данных принимает файл с исходным кодом программы, для которого генерируется НТМL файл. Документация для каждого класса содержится в отдельном НТМL файле. Кроме этого, создается дерево индексов и иерархии. Могут быть сгенерированы и другие НТМL файлы.
Сценарии ant и javadoc
Для создания документации можно использовать ant.
Пример сценария (задания) ant для формирования документации к приложению MyProject :
Подробная информация формирования документации представлена на странице Javadoc/Javadoc2
Java Language Документирование кода Java
Вступление
Документация для Java-кода часто создается с помощью javadoc . Javadoc был создан Sun Microsystems с целью генерации документации API в формате HTML из исходного кода Java. Использование формата HTML дает удобство гиперссылки связанных документов вместе.
Синтаксис
- / ** — запуск JavaDoc в классе, поле, методе или пакете
- @author // Чтобы назвать автора класса, интерфейса или перечисления. Требуется.
- @version // Версия этого класса, интерфейса или перечисления. Требуется. Вы можете использовать макросы, такие как% I% или% G%, для программного обеспечения для управления исходным кодом, которое необходимо заполнить при оформлении заказа.
- @param // Чтобы показать аргументы (параметры) метода или конструктора. Укажите один тег @param для каждого параметра.
- @return // Чтобы показать типы возвращаемых значений для непустых методов.
- @exception // Показывает, какие исключения могут быть выбраны из метода или конструктора. Исключения, которые ДОЛЖНЫ быть пойманы, должны быть перечислены здесь. Если вы хотите, вы можете также включить те, которые не нужно захватывать, например ArrayIndexOutOfBoundsException. Укажите одно исключение @ для каждого исключения, которое может быть выбрано.
- @throws // То же, что @exception.
- @see // Ссылки на метод, поле, класс или пакет. Используйте в виде package.Class # что-то.
- @since // Когда этот метод, поле или класс были добавлены. Например, JDK-8 для класса, такого как java.util.Optional .
- @serial, @serialField, @serialData // Используется для отображения serialVersionUID.
- @deprecated // Чтобы пометить класс, метод или поле как устаревшие. Например, будет java.io.StringBufferInputStream . Смотрите полный список существующих устаревших классов здесь .
- <@link>// Подобно @see, но может использоваться с пользовательским текстом: <@link #setDefaultCloseOperation (int closeOperation) см. JFrame # setDefaultCloseOperation для получения дополнительной информации>.
- <@linkplain>// Похож на <@link>, но без шрифта кода.
- <@code>// Для буквенного кода, например, HTML-тегов. Например: <@code >. Однако это будет использовать моноширинный шрифт. Чтобы получить тот же результат без моноширинного шрифта, используйте <@literal>.
- <@literal>// То же, что и <@code>, но без моноширинного шрифта.
- <@value>// Показывает значение статического поля: значение JFrame # EXIT_ON_CLOSE равно <@value>. Или вы можете ссылаться на определенное поле: Использует имя приложения <@value AppConstants # APP_NAME>.
- <@docRoot>// Корневая папка JavaDoc HTML относительно текущего файла. Пример: Кредиты .
- HTML разрешен: «Привет cookies» .substring (3) .
- * / — конец объявления JavaDoc
замечания
Javadoc — это инструмент, входящий в состав JDK, который позволяет конвертировать комментарии в коде в документацию HTML. Спецификация Java API была сгенерирована с использованием Javadoc. То же самое можно сказать и о большей части документации сторонних библиотек.
