Вступ до 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; }

SuccessfullyAttacked метод містить як опис і численні тег автономного блоку.

Існує багато тегів блоків, які допомагають створити належну документацію, і ми можемо включати всіляку різну інформацію. Ми навіть можемо використовувати основні теги 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.