Въведение в Javadoc

Програмиране

1. Общ преглед

Добрата документация за API е един от многото фактори, допринасящи за цялостния успех на софтуерен проект.

За щастие всички съвременни версии на JDK предоставят инструмента Javadoc - за генериране на API документация от коментари, присъстващи в изходния код.

Предпоставки:

  1. JDK 1.4 (JDK 7+ се препоръчва за последната версия на приставката Maven Javadoc)
  2. Папката JDK / bin е добавена към променливата на средата PATH
  3. (По избор) IDE, който с вградени инструменти

2. Javadoc коментари

Нека започнем с коментари.

Структурата на коментарите на Javadoc изглежда много подобна на обикновения многоредов коментар , но ключовата разлика е допълнителната звездичка в началото:

// This is a single line comment /* * This is a regular multi-line comment */ /** * This is a Javadoc */

Коментарите в стил Javadoc също могат да съдържат HTML тагове.

2.1. Формат на Javadoc

Javadoc коментарите могат да бъдат поставени над всеки клас, метод или поле, които искаме да документираме.

Тези коментари обикновено се състоят от два раздела:

  1. Описанието на това, което коментираме
  2. Самостоятелните блокови маркери (маркирани със символа „ @ “), които описват конкретни метаданни

Ще използваме някои от най-често срещаните блокови тагове в нашия пример. За пълен списък с блокови маркери посетете справочното ръководство.

2.2. Javadoc на ниво клас

Нека да разгледаме как би изглеждал коментар на Javadoc на ниво клас:

/** * Hero is the main entity we'll be using to . . . * * Please see the {@link com.baeldung.javadoc.Person} class for true identity * @author Captain America * */ public class SuperHero extends Person { // fields and methods }

Имаме кратко описание и два различни блокови маркера - самостоятелни и вградени:

  • Самостоятелните тагове се появяват след описанието с маркера като първата дума в ред, например етикетът @author
  • Вградените маркери могат да се появяват навсякъде и са заобиколени от къдрави скоби , например маркера @link в описанието

В нашия пример можем да видим и два вида използвани блокови маркери:

  • {@link} предоставя вградена връзка към посочена част от нашия изходен код
  • @author името на автора, който е добавил класа, метода или полето, което е коментирано

2.3. Javadoc на ниво поле

Можем да използваме и описание без никакви блокови маркери като този в нашия клас SuperHero :

/** * The public name of a hero that is common knowledge */ private String heroName;

Частни полета няма да имат Javadoc генерирана за тях, освен ако не е изрично премине -самостоятелна вариант на командата Javadoc.

2.4. Javadoc на ниво метод

Методите могат да съдържат различни Javadoc блокови тагове.

Нека да разгледаме метод, който използваме:

/** * 
This is a simple description of the method. . . * Superman! * 
 * @param incomingDamage the amount of incoming damage * @return the amount of health hero has after attack * @see HERO-402 * @since 1.0 */ public int successfullyAttacked(int incomingDamage) { // do things return 0; }

Методът успешноAttacked съдържа както описание, така и множество самостоятелни блокови маркери.

Има много блокови маркери, които помагат за генерирането на правилна документация и можем да включим всякакви различни видове информация. Можем дори да използваме основни HTML тагове в коментарите.

Нека да разгледаме маркерите, които срещаме в примера по-горе:

  • @param предоставя всяко полезно описание за параметъра на метода или въведеното от него, което трябва да очаква
  • @return предоставя описание на това, което даден метод ще върне или може да върне
  • @see ще генерира връзка, подобна на маркера {@link} , но повече в контекста на препратка, а не вградена
  • @since указва коя версия класът, полето или методът са добавени към проекта
  • @version указва версията на софтуера, често използвана с макроси% I% и% G%
  • @throws се използва за допълнително обяснение на случаите, в които софтуерът би очаквал изключение
  • @deprecated дава обяснение защо кодът е остарял, кога може да е остарял и какви са алтернативите

Въпреки че и двата раздела са технически незадължителни, ще ни трябва поне един за инструмента Javadoc, за да генерира нещо значимо.

3. Поколение на Javadoc

За да генерираме нашите Javadoc страници, ще искаме да разгледаме инструмента за команден ред, който се доставя с JDK, и приставката Maven.

3.1. Инструмент за команден ред на Javadoc

Инструментът за команден ред Javadoc е много мощен, но има известна сложност, свързана с него.

Изпълнението на командата javadoc без опции или параметри ще доведе до грешка и изходни параметри, които очаква.

Ще трябва поне да посочим за кой пакет или клас искаме да се генерира документация.

Нека отворим команден ред и отидем до директорията на проекта.

Ако приемем, че всички класове са в папката src в директорията на проекта:

[email protected]:~$ javadoc -d doc src\*

Това ще генерира документация в директория, наречена doc, както е посочено с флага - d . Ако съществуват множество пакети или файлове, ще трябва да предоставим всички.

Използването на IDE с вградената функционалност е, разбира се, по-лесно и обикновено се препоръчва.

3.2. Javadoc с приставка Maven

We can also make use of the Maven Javadoc plugin:

   org.apache.maven.plugins maven-javadoc-plugin 3.0.0  1.8 1.8   ...

In the base directory of the project, we run the command to generate our Javadocs to a directory in target\site:

[email protected]:~$ mvn javadoc:javadoc

The Maven plugin is very powerful and facilitates complex document generation seamlessly.

Let's now see what a generated Javadoc page looks like:

We can see a tree view of the classes our SuperHero class extends. We can see our description, fields, and method, and we can click on links for more information.

A detailed view of our method looks like this:

3.3. Custom Javadoc Tags

In addition to using predefined block tags to format our documentation, we can also create custom block tags.

In order to do so, we just need to include a -tag option to our Javadoc command line in the format of ::.

In order to create a custom tag called @location allowed anywhere, which is displayed in the “Notable Locations” header in our generated document, we need to run:

[email protected]:~$ javadoc -tag location:a:"Notable Locations:" -d doc src\*

In order to use this tag, we can add it to the block section of a Javadoc comment:

/** * This is an example... * @location New York * @returns blah blah */

The Maven Javadoc plugin is flexible enough to also allow definitions of our custom tags in our pom.xml.

In order to set up the same tag above for our project, we can add the following to the section of our plugin:

...   location a Notable Places:   ...

This way allows us to specify the custom tag once, instead of specifying it every time.

4. Conclusion

Този урок за бързо въвеждане обхваща как да пишете основни Javadocs и да ги генерирате с командния ред Javadoc.

По-лесен начин за генериране на документацията би бил използването на всякакви вградени IDE опции или включването на приставката Maven в нашия файл pom.xml и изпълнението на съответните команди.

Кодовите мостри, както винаги, могат да бъдат намерени в GitHub.