what is javadoc how use it generate documentation
Цей підручник пояснює, що таке інструмент JavaDoc та коментарі та методи JavaDoc для створення документації коду:
JavaDoc - це спеціальний інструмент, який входить до складу JDK. Він використовується для генерації документації коду вихідного коду Java у форматі HTML.
Це генератор документації для мови Java від Sun Microsystems (в даний час Oracle Corporation).
=> Перевірте ВСІ підручники Java тут.
Що ви дізнаєтесь:
Що таке JavaDoc
Цей інструмент використовує формат “doc comments” для документування класів Java. IDE, такі як Eclipse, IntelliJIDEA або NetBeans, мають вбудований інструмент JavaDoc для створення HTML-документації. У нас також є багато редакторів файлів на ринку, які можуть допомогти програмісту створювати джерела JavaDoc.
Окрім документації до вихідного коду, цей інструмент також надає API, який створює 'doclets' і 'taglets', які ми використовуємо для аналізу структури програми Java.
Варто зазначити, що цей інструмент жодним чином не впливає на продуктивність програми, оскільки компілятор видаляє всі коментарі під час компіляції програми Java.
Написання коментарів у програмі, а потім використання JavaDoc для створення документації має допомогти програмісту / користувачеві зрозуміти код.
Документація HTML, створена JavaDoc, - це документація API. Він аналізує декларації та генерує набір вихідних файлів. Вихідний файл описує поля, методи, конструктори та класи.
Зауважте, що перед тим, як ми використовуємо інструмент JavaDoc у нашому вихідному коді, ми повинні включити в програму спеціальні коментарі JavaDoc.
Перейдемо до коментарів.
Коментарі JavaDoc
Мова Java підтримує такі типи коментарів.
# 1) Однорядкові коментарі: Однорядковий коментар позначається ' // ”І коли компілятор стикається з ними, він ігнорує все, що слідує за цими коментарями до кінця рядка.
# 2) Багаторядкові коментарі: Багаторядкові коментарі представлені за допомогою “ /*….*/ '. Отож, зустрічаючи послідовність «/ *», компілятор ігнорує все, що слідує за цією послідовністю, доки не зустріне завершальну послідовність «* /».
# 3) Коментарі до документації: Вони називаються коментарями до документа, і вони використовуються інструментом для створення документації API. Коментарі до документа вказані як “ / ** документація * / '. Як ми бачимо, ці коментарі відрізняються від звичайних коментарів, описаних вище. Коментарі до документа можуть також містити всередині них теги HTML, як ми скоро побачимо.
які інші постачальники послуг електронної пошти існують
Тому для створення документації API за допомогою цього інструменту ми повинні надати коментарі до цієї документації (коментарі до документації) у нашій програмі.
Структура коментаря JavaDoc
Структура коментаря Doc на Java схожа на багаторядковий коментар, за винятком того, що коментар документа має додаткову зірочку (*) у початковому тегу. Тож коментар документа починається з «/ **» замість «/ *».
Крім того, коментарі стилю JavaDoc також можуть мати теги HTML всередині.
Формат коментарів JavaDoc
На основі конструкції програмування, на якій ми хочемо задокументувати, ми можемо розміщувати коментарі до документації над будь-якою конструкцією, такою як клас, метод, поле тощо. Давайте розглянемо приклади коментарів до документа кожної конструкції.
Формат рівня класу
Формат коментаря до документа на рівні класу буде виглядати так, як показано нижче:
/** * Mechanic * * Please see the {@link sth.javadoctutes.Person} class for true identity * @author SoftwareTestingHelp * */ public class Mechanic extends Person { // fields and methods } Як показано вище, коментар до документа на рівні класу буде містити всі деталі, включаючи автора класу, посилання, якщо такі є, тощо.
Формат рівня методу
Нижче наведено приклад формату документа на рівні методу.
/** * simple method description … * JavaDoc! *
* @param msg the message to be printed * @return void * @see JavaDoc * @since 2.0 */ public void printMessage (String msg) { // do things return 0; } Як ми бачимо з наведеного прикладу, ми можемо мати будь-яку кількість тегів у коментарі до документа методу. Ми також можемо мати абзаци всередині опису коментаря, позначеного як
...
що може зробити c ++.
У нас також є спеціальні теги для опису поверненого значення (@return) та параметрів методу (@param).
Формат рівня поля
У наступному прикладі показано коментар до документа для поля.
/** * The public name of a message */ private String msg_txt;Як видно з наведеного прикладу, ми також можемо мати прості коментарі без будь-яких тегів. Зауважте, що JavaDoc не створює жодної документації для приватних полів, якщо ми не вказали приватний параметр за допомогою команди JavaDoc.
Тепер обговоримо теги, які використовуються з коментарями до документації.
Теги JavaDoc
Java пропонує різні теги, які ми можемо включити до коментаря до документа. Коли ми використовуємо ці теги, інструмент аналізує ці теги, щоб створити добре відформатований API з вихідного коду.
Кожен тег чутливий до регістру і починається зі знака „@”. Кожен тег починається на початку рядка, як ми бачимо з наведених прикладів. В іншому випадку компілятор трактує це як звичайний текст. Як домовленість, однакові теги розміщуються разом.
Існує два типи тегів, які ми можемо використовувати в коментарях до документа.
# 1) Блокувати теги : Блокові теги мають вигляд @tag_name .
Теги блоків можна розміщувати в розділі тегів і слідувати основному опису .
# 2) Вбудовані теги :Вбудовані теги укладені в фігурні дужки та мають форму, {@tag_name} . Вбудовані теги можна розміщувати в будь-якому місці коментаря до документа.
У наступній таблиці перелічені всі теги, які можна використовувати в коментарях до документа.
| Позначка | Опис | Стосується |
|---|---|---|
| @return опис | Надає опис значення повернення. | Метод |
| @author xyz | Вказує автора класу, інтерфейсу або переліку. | Клас, інтерфейс, перелік |
| {@docRoot} | Цей тег має відносний шлях до кореневого каталогу документа. | Клас, інтерфейс, перелік, поле, метод |
| версія @version | Вказує запис версії програмного забезпечення. | Клас, інтерфейс, перелік |
| @ з тих пір, як текст | Вказує, відколи ця функціональність існує | Клас, інтерфейс, перелік, поле, метод |
| @ дивіться посилання | Вказує посилання (посилання) на іншу документацію | Клас, інтерфейс, перелік, поле, метод |
| Опис імені @param | Використовується для опису параметра / аргументу методу. | Метод |
| Опис імені класу @exception | Вказує виняток, який метод може ввести в свій код. | Метод |
| Опис імені класу @throws | ||
| @ застарілий опис | Вказує, чи метод застарілий | Клас, інтерфейс, перелік, поле, метод |
| {@inheritDoc} | Використовується для копіювання опису із заміненого методу у разі успадкування | Заміна методу |
| {@link reference} | Надає посилання або посилання на інші символи. | Клас, інтерфейс, перелік, поле, метод |
| {@linkplain reference} | Те саме, що і {@link}, але відображається у вигляді простого тексту. | Клас, інтерфейс, перелік, поле, метод |
| {@value #STATIC_FIELD} | Опишіть значення статичного поля. | Статичне поле |
| {@code буквальний} | Використовується для форматування буквального тексту шрифтом коду, подібним до {@literal}. | Class, Interface, Enum, Field, Method |
| {@literal literal} | Indicates literal text. the enclosed text is interpreted literally without any style formatting. | Class, Interface, Enum, Field, Method |
| {@serial literal} | Description of a serializable field. | Field |
| {@serialData literal} | Documents the data written by the writeExternal( ) or writeObject( ) methods. | Field, Method |
| {@serialField literal} | Describes an ObjectStreamField component. | Field |
Generate Java Doc
To create a JavaDoc you do not need to compile the Java file. We can generate JavaDoc documentation in two ways.
#1) Using JavaDoc Command Via Command Line
The command-line tool allows us to run the command through it.
This command can be executed on a command line and has the following syntax.
user@sth:~$javadoc –d doc src*
In the above command, we assume that all the files and Java classes are in the src folder. Also, the documentation will be generated in the specified ‘doc’ directory.
Note that running the “javadoc” command without any parameters or flags results in an error.
#2) Using The Tool From Any Of The Java IDEs.
All the major Java IDEs provide built-in functionality of generating documentation using the JavaDoc tool.
Using this built-in functionality is easier and also recommended than using a command-line tool to generate Java documentation.
Using JavaDoc With IntelliJIdea
Let’s generate documentation for a simple program using IntelliJIdea IDE.
We will consider the following program for which we have provided doc comments.
/** * Main class * * Please see the {@link www.softwaretestinghelp.com} class for true identity * @author SoftwareTestingHelp * */ public class Main{ /** * main method description … * JavaDoc! *
* @param args() string array * @return void * @see JavaDoc * */ public static void main(String args()) { System.out.println('Hello,World!!'); } } Ми знаємо, що нам не потрібно компілювати програму чи проект для створення JavaDoc. IntelliJIdea Ide надає вбудований інструмент для генерації документації. Виконайте наведені нижче дії, щоб сформувати документацію за допомогою IntelliJIdea.
- Клацніть Інструменти -> Створити JavaDoc
- Наступний екран відкривається після натискання інструменту JavaDoc.
Тут ми можемо вказати, чи хочемо ми генерувати документацію для всього проекту або лише для одного класу і т. Д. Ми також можемо вказати вихідний каталог, де будуть створюватися файли документації. Існують різні інші технічні характеристики, як показано на малюнку вище.
Клацніть OK, як тільки будуть вказані всі параметри.
- Тепер ми можемо побачити процес генерації Java Doc у вікні виводу. Зразок вікна виводу Java Doc виглядає, як показано нижче:
- Після завершення генерації генеруються такі файли.
- Як ми вказали клас Main, генерується файл Main.html. Зверніть увагу, що index.html також має той самий вміст, що і Main.html.
- Файл help-doc.html містить загальні визначення сутностей Java. Зразок вмісту цього файлу наведено нижче.
- Аналогічно, нижче наведено зразок вмісту у файлі Main.html
Таким чином, таким чином ми можемо створювати документацію, використовуючи цей інструмент в ідеї IntelliJ. Ми можемо виконувати подібні дії в інших середовищах розробки Java, таких як Eclipse та / або NetBeans.
Часті запитання
Q # 1) Яка користь JavaDoc?
Відповідь: Інструмент JavaDoc постачається з JDK. Він використовується для створення документації коду для вихідного коду Java у форматі HTML. Цей інструмент вимагає, щоб коментарі у вихідному коді подавались у заздалегідь визначеному форматі як /**….*/. Вони також називаються коментарями до документації.
Q # 2) Який приклад документації щодо Java?
Відповідь: Засіб документації Java Doc генерує файли HTML, щоб ми могли переглядати документацію з веб-браузера. Реальним реальним прикладом документації JavaDoc є документація для бібліотек Java корпорації Oracle, http://download.oracle.com/javase/6/ документи / вогонь /.
Q # 3) Чи потрібні приватні методи JavaDoc?
Відповідь: Ні. Приватні поля та методи призначені лише для розробників. Немає логіки у наданні документації для приватних методів або полів, недоступних для кінцевого користувача. Java Doc також не створює документацію для приватних організацій.
який найкращий обліковий запис електронної пошти мати
Q # 4) Що таке JavaDoc Command?
Відповідь: Ця команда аналізує декларації та коментарі до документації у вихідних файлах Java та генерує відповідні сторінки документації HTML, що містять документацію для загальнодоступних та захищених класів, вкладених класів, конструкторів, методів, полів та інтерфейсів.
Однак JavaDoc не створює документацію для приватних сутностей та анонімних внутрішніх класів.
Висновок
У цьому посібнику описано інструмент JavaDoc, упакований з JDK, який корисний для створення документації коду для вихідного коду Java у форматі HTML. Ми можемо генерувати документацію, виконуючи команду Java Doc за допомогою командного інструменту, або використовуючи вбудовану функціональність JavaDoc, доступну в більшості IDE Java.
Ми побачили, як ми можемо використовувати інструмент із IntelliJIdea Java IDE для створення документації. У навчальному посібнику також пояснені різні теги, які можна використовувати з коментарями до документації, щоб засіб міг створювати зручну для користувача документацію, що деталізує всю інформацію, пов’язану з вихідним кодом.
=> Завітайте сюди, щоб вивчити Java з нуля.
Рекомендована література
- Основи Java: Синтаксис Java, клас Java та основні концепції Java
- Розгортання Java: створення та виконання файлу Java JAR
- Віртуальна машина Java: як JVM допомагає у запуску програми Java
- Підручник JAVA для початківців: 100+ практичних навчальних посібників Java
- Java Integer та клас Java BigInteger з прикладами
- Компоненти Java: платформа Java, JDK, JRE та віртуальна машина Java
- Як створити документацію API у поштарці?