38. Java – Javadoc
Эта глава посвящена как пользоваться Javadoc. Мы посмотрим, как мы можем использовать Javadoc для создания полезной документации для кода Java.
Что такое Javadoc?
Javadoc – это инструмент, который поставляется с JDK и используется для создания документации кода Java в формате HTML из исходного кода Java, для чего требуется документация в заранее определенном формате.
Ниже приводится простой пример, в котором строки внутри /*….*/ представляют собой многострочные комментарии Java. Точно так же строка, предшествующая //, является однострочным комментарием Java.
Пример 1
/** * Программа HelloWorld реализует приложение, которое * выводит "Привет, Мир!" на стандартном потоке вывода. * * @автор Zara Ali * @версия 1.0 * @от 2014-03-31 */ public class HelloWorld < public static void main(String[] args) < // Выводит "Привет, Мир!" на стандартном потоке вывода. System.out.println("Привет, Мир!"); >> Вы можете включить необходимые HTML-теги внутри части описания. Например, в следующем примере используется
.
для заголовка, а
используется для создания разрыва абзаца.
Пример 2
/** * Привет, Мир!
* Программа HelloWorld реализует приложение, которое * выводит "Привет, Мир!" на стандартном потоке вывода. * * Правильные комментарии в вашей программе делают ее более * удобной для пользователя и предполагается, что этот код является * более высококачественным. * * @ автор Zara Ali * @ версия 1.0 * @ от 2014-03-31 */ public class HelloWorld < public static void main(String[] args) < // Выводит "Привет, Мир! " на стандартном потоке вывода. System.out.println("Привет, Мир!"); >>
Теги Javadoc
Инструмент javadoc распознает следующие теги:
| Тег | Описание | Синтаксис |
| @author | Добавляет автора класса. | @author name-text |
| Отображает текст шрифтом кода без интерпретации текста как разметки HTML или вложенных тегов javadoc. | ||
| Представляет относительный путь к корневому каталогу сгенерированного документа от любой сгенерированной страницы. | ||
| @deprecated | Добавляет комментарий, указывающий, что этот прикладной программный интерфейс больше не следует использовать. | @deprecated deprecatedtext |
| @exception | Добавляет подзаголовок Throws в сгенерированную документацию с именем класса и текстом описания | @exception class-name description |
| Наследует комментарий от ближайшего наследуемого класса или реализуемого интерфейса | Inherits a comment from the immediate surperclass. | |
| Вставляет встроенную ссылку с видимой текстовой меткой, которая указывает на документацию для указанного пакета, класса или имени члена указанного класса. | ||
| Идентично , за исключением того, что подпись ссылки отображается в виде обычного текста, а не шрифта кода. | ||
| @param | Добавляет параметр с указанным именем параметра, за которым следует указанное описание, в раздел «Параметры». | @param parameter-name description |
| @return | Добавляет раздел «Возврат» с текстом описания. | @return description |
| @see | Добавляет заголовок «Смотрите также» со ссылкой или текстовой записью, указывающей на ссылку. | @see reference |
| @serial | Используется в комментарии к документу для сериализуемого поля по умолчанию. | @serial field-description | include | exclude |
| @serialData | Документирует данные, записанные методами writeObject() или writeExternal(). | @serialData data-description |
| @serialField | Документирует компонент ObjectStreamField. | @serialField field-name field-type field-description |
| @since | Добавляет заголовок «От» с указанным текстом в созданную документацию. | @since release |
| @throws | Теги @throws и @exception являются синонимами. | @throws class-name description |
| Когда используется в комментарии к документу статического поля, он отображает значение этой константы. | ||
| @version | Добавляет подзаголовок «Версия» с указанным текстом версии в сгенерированные документы при использовании параметра -version. | @version version-text |
Пример
Следующая программа использует несколько важных тегов, доступных для комментариев к документации. Вы можете использовать другие теги в зависимости от ваших требований.
Документация о классе AddNum будет создана в HTML-файле AddNum.html, но в то же время будет создан главный файл с названием index.html.
import java.io.*; /** * Сложите два числа!
* Программа AddNum реализует приложение, которое * просто складывает два заданных целых числа и выводит * результат на экран. * * Примечание: Правильные комментарии в вашей программе * удобной для пользователя и предполагается, что этот код является * более высококачественным. * * @автор Zara Ali * @версия 1.0 * @от 2014-03-31 */ public class AddNum < /** * Этот метод используется для сложения двух целых чисел. Это * простейшая форма метода класса, просто чтобы * показать использование различных тегов javadoc. * @param numA Это первый параметр метода addNum * @param numB Это второй параметр метода addNum * @return int Это возвращает сумму numA и numB. */ public int addNum(int numA, int numB) < return numA + numB; >/** * Это основной метод, использующий метод addNum. * @param args Не используется. * @return Ничего. * @exception IOException При ошибке ввода. * @see IOException */ public static void main(String args[]) throws IOException < AddNum obj = new AddNum(); int sum = obj.addNum(10, 20); System.out.println("Суммой 10 и 20 является :" + sum); >>
Теперь обработайте указанный выше файл AddNum.java с помощью утилиты javadoc следующим образом:
$ javadoc AddNum.java Загрузка исходного файла AddNum.java . Создание информации Javadoc . Версии стандартного Doclet 1.7.0_51 Построение схемы в виде дерева для всех пакетов и классов . Создание /AddNum.html . AddNum.java:36: предупреждение - тег @return не может использоваться в методе с типом возврата void. Создание /package-frame.html . Создание /package-summary.html . Создание /package-tree.html . Создание /constant-values.html . Построение индекса для всех пакетов и классов . Создание /overview-tree.html . Создание /index-all.html . Создание /deprecated-list.html . Построение индекса для всех классов . Создание /allclasses-frame.html . Создание /allclasses-noframe.html . Создание /index.html . Создание /help-doc.html . 1 предупреждение $ Если вы используете JDK 1.7, то javadoc не создает большой stylesheet.css, поэтому мы предлагаем загрузить и использовать стандартную таблицу стилей по ссылке https://docs.oracle.com/javase/7/docs/api/stylesheet.css
Оглавление
- 1. Java – Самоучитель для начинающих
- 2. Java – Обзор языка
- 3. Java – Установка и настройка
- 4. Java – Синтаксис
- 5. Java – Классы и объекты
- 6. Java – Конструкторы
- 7. Java – Типы данных и литералы
- 8. Java – Типы переменных
- 9. Java – Модификаторы
- 10. Java – Операторы
- 11. Java – Циклы и операторы цикла
- 11.1. Java – Цикл while
- 11.2. Java – Цикл for
- 11.3. Java – Улучшенный цикл for
- 11.4. Java – Цикл do..while
- 11.5. Java – Оператор break
- 11.6. Java – Оператор continue
- 12. Java – Операторы принятия решений
- 12.1. Java – Оператор if
- 12.2. Java – Оператор if..else
- 12.3. Java – Вложенный оператор if
- 12.4. Java – Оператор switch..case
- 12.5. Java – Условный оператор (? 🙂
- 13. Java – Числа
- 13.1. Java – Методы byteValue(), shortValue(), intValue(), longValue(), floatValue(), doubleValue()
- 13.2. Java – Метод compareTo()
- 13.3. Java – Метод equals()
- 13.4. Java – Метод valueOf()
- 13.5. Java – Метод toString()
- 13.6. Java – Метод parseInt()
- 13.7. Java – Метод Math.abs()
- 13.8. Java – Метод Math.ceil()
- 13.9. Java – Метод Math.floor()
- 13.10. Java – Метод Math.rint()
- 13.11. Java – Метод Math.round()
- 13.12. Java – Метод Math.min()
- 13.13. Java – Метод Math.max()
- 13.14. Java – Метод Math.exp()
- 13.15. Java – Метод Math.log()
- 13.16. Java – Метод Math.pow()
- 13.17. Java – Метод Math.sqrt()
- 13.18. Java – Метод Math.sin()
- 13.19. Java – Метод Math.cos()
- 13.20. Java – Метод Math.tan()
- 13.21. Java – Метод Math.asin()
- 13.22. Java – Метод Math.acos()
- 13.23. Java – Метод Math.atan()
- 13.24. Java – Метод Math.atan2()
- 13.25. Java – Метод Math.toDegrees()
- 13.26. Java – Метод Math.toRadians()
- 13.27. Java – Метод Math.random()
- 14. Java – Символы
- 14.1. Java – Метод Character.isLetter()
- 14.2. Java – Метод Character.isDigit()
- 14.3. Java – Метод Character.isWhitespace()
- 14.4. Java – Метод Character.isUpperCase()
- 14.5. Java – Метод Character.isLowerCase()
- 14.6. Java – Метод Character.toUpperCase()
- 14.7. Java – Метод Character.toLowerCase()
- 14.8. Java – Метод Character.toString()
- 15. Java – Строки
- 15.1. Java – Метод charAt()
- 15.2. Java – Метод compareTo()
- 15.3. Java – Метод compareToIgnoreCase()
- 15.4. Java – Метод concat()
- 15.5. Java – Метод contentEquals()
- 15.6. Java – Метод copyValueOf()
- 15.7. Java – Метод endsWith()
- 15.8. Java – Метод equals()
- 15.9. Java – Метод equalsIgnoreCase()
- 15.10. Java – Метод getBytes()
- 15.11. Java – Метод getChars()
- 15.12. Java – Метод hashCode()
- 15.13. Java – Метод indexOf()
- 15.14. Java – Метод intern()
- 15.15. Java – Метод lastIndexOf()
- 15.16. Java – Метод length()
- 15.17. Java – Метод matches()
- 15.18. Java – Метод regionMatches()
- 15.19. Java – Метод replace()
- 15.20. Java – Метод replaceAll()
- 15.21. Java – Метод replaceFirst()
- 15.22. Java – Метод split()
- 15.23. Java – Метод startsWith()
- 15.24. Java – Метод subSequence()
- 15.25. Java – Метод substring()
- 15.26. Java – Метод toCharArray()
- 15.27. Java – Метод toLowerCase()
- 15.28. Java – Метод toString()
- 15.29. Java – Метод toUpperCase()
- 15.30. Java – Метод trim()
- 15.31. Java – Метод valueOf()
- 15.32. Java – Классы StringBuilder и StringBuffer
- 15.32.1. Java – Метод append()
- 15.32.2. Java – Метод reverse()
- 15.32.3. Java – Метод delete()
- 15.32.4. Java – Метод insert()
- 15.32.5. Java – Метод replace()
- 16. Java – Массивы
- 17. Java – Дата и время
- 18. Java – Регулярные выражения
- 19. Java – Методы
- 20. Java – Потоки ввода/вывода, файлы и каталоги
- 20.1. Java – Класс ByteArrayInputStream
- 20.2. Java – Класс DataInputStream
- 20.3. Java – Класс ByteArrayOutputStream
- 20.4. Java – Класс DataOutputStream
- 20.5. Java – Класс File
- 20.6. Java – Класс FileReader
- 20.7. Java – Класс FileWriter
- 21. Java – Исключения
- 21.1. Java – Встроенные исключения
- 22. Java – Вложенные и внутренние классы
- 23. Java – Наследование
- 24. Java – Переопределение
- 25. Java – Полиморфизм
- 26. Java – Абстракция
- 27. Java – Инкапсуляция
- 28. Java – Интерфейсы
- 29. Java – Пакеты
- 30. Java – Структуры данных
- 30.1. Java – Интерфейс Enumeration
- 30.2. Java – Класс BitSet
- 30.3. Java – Класс Vector
- 30.4. Java – Класс Stack
- 30.5. Java – Класс Dictionary
- 30.6. Java – Класс Hashtable
- 30.7. Java – Класс Properties
- 31. Java – Коллекции
- 31.1. Java – Интерфейс Collection
- 31.2. Java – Интерфейс List
- 31.3. Java – Интерфейс Set
- 31.4. Java – Интерфейс SortedSet
- 31.5. Java – Интерфейс Map
- 31.6. Java – Интерфейс Map.Entry
- 31.7. Java – Интерфейс SortedMap
- 31.8. Java – Класс LinkedList
- 31.9. Java – Класс ArrayList
- 31.10. Java – Класс HashSet
- 31.11. Java – Класс LinkedHashSet
- 31.12. Java – Класс TreeSet
- 31.13. Java – Класс HashMap
- 31.14. Java – Класс TreeMap
- 31.15. Java – Класс WeakHashMap
- 31.16. Java – Класс LinkedHashMap
- 31.17. Java – Класс IdentityHashMap
- 31.18. Java – Алгоритмы Collection
- 31.19. Java – Iterator и ListIterator
- 31.20. Java – Comparator
- 32. Java – Дженерики
- 33. Java – Сериализация
- 34. Java – Сеть
- 34.1. Java – Обработка URL
- 35. Java – Отправка Email
- 36. Java – Многопоточность
- 36.1. Java – Синхронизация потоков
- 36.2. Java – Межпоточная связь
- 36.3. Java – Взаимная блокировка потоков
- 36.4. Java – Управление потоками
- 37. Java – Основы работы с апплетами
- 38. Java – Javadoc
How to write Java Doc
In this tutorial, we will learn how to write a Java Documentation (Java Doc or Javadoc) and the usage of JavaDoc tags.
1. Java Doc – Introduction
We can use any JavaDoc tool of their preference or the ALT + SHIFT + J key for generating a standard HTML documentation. In this tutorial, we will primarily focus on the keyboard keys but before going further let us take a deep dive at the Javadoc’s.
1.1 What is JavaDoc?
- JavaDoc comments begin with /** and ends with */
- It consists of a description which is followed by the block tags
- To generate the documentation, developers can write the following command in command line i.e.
1.2 JavaDoc Tags
The following table lists the commonly used JavaDoc tags.
| Tags | Meaning | Used over? |
| @see | Name of the associated class | Class, method |
| @author | Author information such as name, email address, website, etc. | Class |
| @version | Version information of a Class, Interface, or an Enum | Class |
| @param | Constructor’s or Method’s input parameters information | Method |
| @return | Information about the Return value of a method | Method |
| @exception | Generated Exception in case of an invalid value | Method |
| @throws | Generated Exception in case of an invalid value | Method |
| @deprecated | Defines the element as deprecated/obsolete. Used by the compiler to generate the warnings | Class, Method |
| @since | The API version in which this class, method, or a field was added | Class, Method |
To start with the captioned tutorial, we are hoping that users at present have their preferred Ide installed on their machines. For easy usage, I am using Eclipse Ide on a Windows operating system.
2. How to write Java Doc
We’ll demonstrate the use of commonly used JavaDoc tags in the software programming world. For a better understanding, developers can execute the below code in Eclipse Ide.
2.1 Example
Consider the following case that consists of two methods and their relevant JavaDoc.