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) Коментари на документацията: Те се наричат Doc коментари и те се използват от инструмента за генериране на API документация. Коментарите на документа са посочени като „ / ** документация * / ”. Както виждаме, тези коментари се различават от нормалните коментари, описани по-горе. Коментарите на документа могат също да съдържат HTML тагове вътре в тях, както ще видим скоро.
най-лесният начин да добавите стойностите в масив е да използвате
Така че, за да генерираме API документация с помощта на този инструмент, трябва да предоставим тези коментари към документацията (коментари на документа) в нашата програма.
Структура на JavaDoc коментар
Структурата на Doc comment в 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 | Показва автора на клас, интерфейс или изброяване. | Клас, интерфейс, Enum |
| {@docRoot} | Този маркер има относителния път към основната директория на документа. | Клас, интерфейс, преброяване, поле, метод |
| @version версия | Задава въвеждане на версията на софтуера. | Клас, интерфейс, Enum |
| @since since-text | Указва от кога тази функционалност съществува | Клас, интерфейс, преброяване, поле, метод |
| @ вижте справка | Посочва препратки (връзки) към друга документация | Клас, интерфейс, преброяване, поле, метод |
| Описание на името на @param | Използва се за описание на параметъра / аргумента на метода. | Метод |
| @exception описание на името на класа | Посочва изключение, което методът може да въведе в своя код. | Метод |
| @throws описание на името на класа | ||
| @отрицано описание | Посочва дали методът е остарял | Клас, интерфейс, преброяване, поле, метод |
| {@inheritDoc} | Използва се за копиране на описанието от заменения метод в случай на наследяване | Отменящ метод |
| {@link reference} | Предоставя препратки или връзки към други символи. | Клас, интерфейс, преброяване, поле, метод |
| {@linkplain справка} | Същото като {@link}, но се показва в обикновен текст. | Клас, интерфейс, преброяване, поле, метод |
| {@value #STATIC_FIELD} | Опишете стойността на статично поле. | Статично поле |
| {@code literal} | Използва се за форматиране на буквалния текст с кодов шрифт, подобен на {@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 IDE като Eclipse и / или NetBeans.
често задавани въпроси
В # 1) Каква е ползата от JavaDoc?
Отговор: Инструментът JavaDoc се предлага с JDK. Използва се за генериране на документацията на кода за изходния код на Java в HTML формат. Този инструмент изисква коментарите в изходния код да бъдат предоставени в предварително зададен формат като /**….*/. Те също се наричат doc коментари.
В # 2) Какъв е примерът за документация за Java?
Отговор: Инструментът за документация на Java Doc генерира HTML файлове, така че да можем да преглеждаме документацията от уеб браузъра. Истинският пример на живо за документация за JavaDoc е документацията за Java библиотеки в Oracle Corporation, http://download.oracle.com/javase/6/ документи / огън /.
В # 3) Нужни ли са частни методи JavaDoc?
Отговор: Не. Частните полета и методи са само за разработчици. Няма логика в предоставянето на документация за частни методи или полета, които не са достъпни за крайния потребител. Java Doc също не генерира документация за частни субекти.
php интервю въпроси и отговори pdf
В # 4) Какво представлява JavaDoc Command?
Отговор: Тази команда анализира декларациите и коментарите на документите в изходните файлове на Java и генерира съответни HTML страници с документация, съдържащи документация за публични и защитени класове, вложени класове, конструктори, методи, полета и интерфейси.
JavaDoc обаче не генерира документация за частни обекти и анонимни вътрешни класове.
Заключение
Този урок описва инструмента JavaDoc, пакетиран с JDK, който е полезен за генериране на кодовата документация за изходния код на Java в HTML формат. Можем да генерираме документация, като изпълняваме командата Java Doc чрез команден инструмент или използваме вградената функционалност JavaDoc, налична в повечето Java IDE.
Видяхме как можем да използваме инструмента с 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 документация в пощальон?