what is javadoc how use it generate documentation
Овај водич објашњава шта су ЈаваДоц алат и ЈаваДоц коментари и методе за генерисање документације кода:
ЈаваДоц је специјални алат који је упакован у ЈДК. Користи се за генерисање документације кода изворног кода Јава у ХТМЛ формату.
То је генератор документације за језик Јава компаније Сун Мицросистемс (тренутно Орацле Цорпоратион).
=> Овде проверите СВЕ Јава туторијале.
Шта ћете научити:
Шта је ЈаваДоц
Овај алат користи формат „доц цомментс“ за документовање Јава класа. ИДЕ-и попут Ецлипсе, ИнтеллиЈИДЕА или НетБеанс имају уграђени ЈаваДоц алат за генерисање ХТМЛ документације. Такође на тржишту имамо много уређивача датотека који програмеру могу помоћи у стварању ЈаваДоц извора.
Поред документације изворног кода, овај алат такође нуди АПИ који креира „доцлетс“ и „таглетс“ које користимо за анализу структуре Јава апликације.
Треба напоменути да овај алат ни на који начин не утиче на перформансе апликације јер компајлер уклања све коментаре током компајлирања Јава програма.
Писање коментара у програму, а затим коришћење ЈаваДоца за генерисање документације помаже програмеру / кориснику да разуме код.
ХТМЛ документација коју генерише ЈаваДоц је АПИ документација. Анализира декларације и генерише скуп изворних датотека. Изворна датотека описује поља, методе, конструкторе и класе.
Имајте на уму да пре него што користимо алат ЈаваДоц на изворном коду, у програм морамо да уврстимо посебне коментаре ЈаваДоц.
Пређимо сада на коментаре.
ЈаваДоц коментари
Јава језик подржава следеће типове коментара.
# 1) Једноредни коментари: Коментар у једном реду означен је са „ // ”И када се компајлер сусретне са њима, игнорише све што следи након ових коментара до краја реда.
# 2) Вишередни коментари: Вишередни коментари су представљени помоћу „ /*….*/ ”. Дакле, приликом сусрета са секвенцом „/ *“, преводилац игнорише све што следи ову секвенцу док не наиђе на закључну секвенцу „* /“.
# 3) Коментари о документацији: Они се називају Доц коментари и алат их користи за генерисање АПИ документације. Коментари докумената су назначени као „ / ** документација * / ”. Као што видимо, ови коментари се разликују од уобичајених горе описаних коментара. Коментари документа такође могу садржати ХТМЛ ознаке у себи, као што ћемо ускоро видети.
бесплатна алтернатива брзим књигама за мала предузећа
Дакле, да бисмо генерисали АПИ документацију помоћу овог алата, морамо пружити коментаре ове документације (коментаре докумената) у нашем програму.
Структура ЈаваДоц коментара
Структура документа Доц у Јави слична је вишередном коментару, осим што коментар документа има додатну звездицу (*) у уводној ознаци. Дакле, коментар документа почиње са „/ **“ уместо са „/ *“.
Поред тога, коментари у стилу ЈаваДоц такође могу имати ХТМЛ ознаке у себи.
ЈаваДоц формат коментара
На основу конструкције програмирања на којој желимо да документујемо, можемо да ставимо коментаре доктора изнад било које конструкције попут класе, методе, поља итд. Прођимо кроз примере коментара документа сваке конструкције.
Формат нивоа класе
Формат коментара документа на нивоу класе изгледаће као што је приказано доле:
/** * 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; } Као што видимо из горњег примера, у коментару документа методе можемо имати било који број ознака. Такође можемо имати пасусе унутар описа коментара означеног са
...
.Такође имамо посебне ознаке за опис повратне вредности (@ретурн) и параметара методе (@парам).
Формат нивоа поља
Следећи пример приказује коментар документа за поље.
/** * The public name of a message */ private String msg_txt;Као што се види из горњег примера, такође можемо имати обичне коментаре без икаквих ознака. Имајте на уму да ЈаваДоц не генерише никакву документацију за приватна поља, осим ако наредбом ЈаваДоц не одредимо приватну опцију.
Хајде сада да разговарамо о ознакама које се користе са коментарима на документ.
ЈаваДоц ознаке
Јава нуди разне ознаке које можемо укључити у коментар на документ. Када користимо ове ознаке, алат рашчлањује те ознаке да би генерисао добро форматирани АПИ из изворног кода.
Свака ознака разликује велика и мала слова и започиње знаком „@“. Свака ознака започиње на почетку реда као што видимо из горњих примера. Иначе, преводилац га третира као нормалан текст. Као договор, исте ознаке се постављају заједно.
Постоје две врсте ознака које можемо користити у коментару на документ.
# 1) Блокирај ознаке : Ознаке блокова имају облик @Означи име .
Ознаке блокова могу се сместити у одељак ознака и следити главни опис .
како отворити .бин датотеке на Виндовс 10
# 2) Уграђене ознаке :Уметнуте ознаке су затворене у витичасте заграде и облика су, {@Означи име} . Уметнуте ознаке могу се поставити било где унутар коментара документа.
Следећа табела наводи све ознаке које се могу користити у коментарима на документ.
| Таг | Опис | Се односи на |
|---|---|---|
| @ повратак опис | Пружа опис враћене вредности. | Метод |
| @аутор киз | Означава аутора класе, интерфејса или набрајања. | Класа, интерфејс, енум |
| {@доцРоот} | Ова ознака има релативну путању до основног директоријума документа. | Класа, интерфејс, набрајање, поље, метода |
| верзија @ верзије | Одређује унос верзије софтвера. | Класа, интерфејс, енум |
| @ пошто је-текст | Одређује од када ова функција постоји | Класа, интерфејс, набрајање, поље, метода |
| @ види референцу | Наводи референце (везе) на другу документацију | Класа, интерфејс, набрајање, поље, метода |
| @парам опис имена | Користи се за опис параметра / аргумента методе. | Метод |
| @екцептион опис назива класе | Одређује изузетак који метод може убацити у свој код. | Метод |
| @тхровс опис назива класе | ||
| @ застарео опис | Одређује да ли је метода застарела | Класа, интерфејс, набрајање, поље, метода |
| {@инхеритДоц} | Користи се за копирање описа из замењене методе у случају наследства | Замена метода |
| {@линк референце} | Пружа референце или везе до других симбола. | Класа, интерфејс, набрајање, поље, метода |
| {@линкплаин референце} | Исто као и {@линк}, али је приказано у обичном тексту. | Класа, интерфејс, набрајање, поље, метода |
| {@валуе #СТАТИЦ_ФИЕЛД} | Опишите вредност статичког поља. | Статичко поље |
| {@цоде литерал} | Користи се за форматирање дословног текста фонтом кода сличним {@литерал}. | 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!!'); } } Знамо да не треба да компајлирамо програм или пројекат за генерисање ЈаваДоц-а. ИнтеллиЈИдеа Иде пружа уграђени алат за генерисање документације. Следите кораке у наставку да бисте генерисали документацију помоћу програма ИнтеллиЈИдеа.
- Кликните Алати -> Генериши ЈаваДоц
- Следећи екран се отвара када се кликне на алат ЈаваДоц.
Овде можемо одредити да ли желимо да генеришемо документацију за цео пројекат или само за једну класу итд. Такође можемо одредити излазни директоријум у којем ће се генерисати датотеке са документацијом. Постоје разне друге спецификације као што је приказано на горњој слици.
Кликните ОК када су наведени сви параметри.
- Сада у прозору за излаз можемо видети процес генерисања Јава Доц-а. Пример прозора за излаз Јава Доц изгледа као што је приказано доле:
- Када се генерација заврши, генеришу се следеће датотеке.
- Као што смо навели класу Маин, генерише се датотека Маин.хтмл. Имајте на уму да индек.хтмл такође има исти садржај као Маин.хтмл.
- Датотека хелп-доц.хтмл садржи опште дефиниције Јава ентитета. Узорак садржаја ове датотеке приказан је у наставку.
- Слично томе, доле је дат примерак садржаја у датотеци Маин.хтмл
Дакле, ово је начин на који можемо генерирати документацију помоћу овог алата у идеји ИнтеллиЈ. Можемо следити сличне кораке у другим Јава ИДЕ-има попут Ецлипсе и / или НетБеанс.
Често постављана питања
П # 1) Чему служи ЈаваДоц?
Одговор: ЈаваДоц алат долази са ЈДК. Користи се за генерисање документације кода за Јава изворни код у ХТМЛ формату. Ова алатка захтева да се коментари у изворном коду дају у унапред дефинисаном формату као /**….*/. Они се такође називају доц коментари.
П # 2) Који је пример Јава документације?
Одговор: Алат за документацију Јава Доц генерише ХТМЛ датотеке тако да можемо да их прегледамо из веб прегледача. Прави живи пример ЈаваДоц документације је документација за Јава библиотеке у компанији Орацле Цорпоратион, хттп://довнлоад.орацле.цом/јавасе/6/ доцс / ватра /.
П # 3) Да ли је приватним методама потребан ЈаваДоц?
Одговор: Не. Приватна поља и методе су само за програмере. Нема логике у обезбеђивању документације за приватне методе или поља која нису доступна крајњем кориснику. Јава Доц такође не генерише документацију за приватне ентитете.
бесплатни софтвер за конверзију видео записа за рачунаре
П # 4) Шта је ЈаваДоц наредба?
Одговор: Ова наредба рашчлањује декларације и коментаре докумената у изворним датотекама Јава и генерише одговарајуће странице ХТМЛ документације које садрже документацију за јавне и заштићене класе, угнежђене класе, конструкторе, методе, поља и интерфејсе.
Међутим, ЈаваДоц не генерише документацију за приватне ентитете и анонимне унутрашње класе.
Закључак
Овај водич је описао ЈаваДоц алат упакован у ЈДК који је користан за генерисање документације кода за Јава изворни код у ХТМЛ формату. Документацију можемо генерисати извршавањем наредбе Јава Доц помоћу командног алата или употребом уграђене ЈаваДоц функције доступне у већини Јава ИДЕ-а.
Видели смо како можемо да користимо алатку са ИнтеллиЈИдеа Јава ИДЕ за генерисање документације. Водич је такође објаснио разне ознаке које се могу користити са коментарима на документ, тако да алат може да генерише корисничку документацију која детаљно описује све информације повезане са изворним кодом.
=> Посетите овде да бисте научили Јаву из нуле.
Препоручено читање
- Основе Јава-а: Јава синтакса, Јава Цласс и основни Јава концепти
- Примена Јава-а: Стварање и извршавање Јава ЈАР датотеке
- Јава виртуелна машина: како ЈВМ помаже у покретању Јава апликације
- Водич за ЈАВА за почетнике: 100+ практичних Јава видео водича
- Јава Интегер и Јава БигИнтегер класа са примерима
- Јава компоненте: Јава платформа, ЈДК, ЈРЕ и Јава виртуелна машина
- Како створити АПИ документацију у поштару?