Java DocLint

1. Обзор

Есть так много причин, по которым использование Javadoc является хорошей идеей. Например, мы можем сгенерировать HTML из нашего Java-кода, просмотреть их определения и обнаружить различные связанные с ними свойства.

Кроме того, это облегчает общение между разработчиками и улучшает ремонтопригодность . Java DocLint — это инструмент для анализа нашего Javadoc. Он выдает предупреждения и ошибки всякий раз, когда обнаруживает неверный синтаксис.

В этом уроке мы сосредоточимся на том, как мы можем его использовать. Позже мы рассмотрим проблемы, которые он может создать в определенных ситуациях, а также некоторые рекомендации о том, как их избежать.

2. Как использовать DocLint

Предположим, у нас есть файл класса с именем Sample.java :

/**
 * This sample file creates a class that
 * just displays sample string on standard output.
 *
 * @autho  ForEach
 * @version 0.9
 * @since   2020-06-13 
 */
public class Sample {

    public static void main(String[] args) {
        // Prints Sample! on standard output.
        System.out.println("Sample!");
    }
}

Намеренно, здесь опечатка, параметр @author пишется @auto . Давайте посмотрим, что произойдет, если мы попытаемся сделать Javadoc без DocLint :

Как видно из вывода консоли, механизм Javadoc не смог определить ошибку в нашей документации и не выдал никаких ошибок или предупреждений.

Чтобы Java DocLint возвращал предупреждение такого типа, мы должны выполнить команду javadoc с параметром – Xdoclint . (мы объясним это подробно позже):

Как видно из вывода, ошибка прямо упоминается в строке 5 нашего Java-файла:

Sample.java:5: error: unknown tag: autho
 * @autho  ForEach
   ^

3. -Xdoclint

Параметр -Xdoclint имеет три варианта для разных целей. Мы быстро рассмотрим каждый из них.

3.1. никто

Параметр none отключает параметр -Xdoclint :

javadoc -Xdoclint:none Sample.java

3.2. группа

Эта опция полезна, когда мы хотим применить определенные проверки, относящиеся к определенным группам, например:

javadoc -Xdoclint:syntax Sample.java

Существует несколько типов групповых переменных:

• доступность — проверяет наличие проблем, которые должны быть обнаружены средством проверки доступности (например, отсутствие атрибутов заголовка или сводки, указанных в теге таблицы )
• html — обнаруживает проблемы HTML высокого уровня, такие как размещение блочных элементов внутри встроенных элементов или отсутствие закрытия элементов, для которых требуется закрывающий тег.
• отсутствует — проверяет наличие отсутствующих комментариев или тегов Javadoc (например, отсутствующий комментарий или класс, отсутствующий тег @return или аналогичный тег в методе)
• reference — проверяет наличие проблем, связанных со ссылками на элементы Java API из тегов Javadoc (например, элемент не найден в @see или плохое имя после @param )
• синтаксис — проверяет низкоуровневые проблемы, такие как неэкранированные угловые скобки (< и >) и амперсанды (>), а также недопустимые теги Javadoc

Можно применить несколько групп одновременно:

javadoc -Xdoclint:html,syntax,accessibility Sample.java

3.3. все

Эта опция включает все группы сразу, но что, если мы хотим исключить некоторые из них?

Мы могли бы использовать синтаксис -group :

javadoc -Xdoclint:all,-missing

4. Как отключить DocLint

Поскольку Java DocLint не существовало до Java 8 , это может создать нежелательные проблемы, особенно в старых сторонних библиотеках.

Мы уже видели вариант none с командой javadoc в предыдущем разделе. Кроме того, есть возможность отключить DocLint в таких системах сборки, как Maven, Gradle, Ant. Мы увидим их в следующих нескольких подразделах.

4.1. Мавен

В maven-javadoc-plugin , начиная с версии 3.0.0, добавлена новая конфигурация doclint . Давайте посмотрим, как настроить его для отключения DocLint:

<plugins>
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>3.1.1</version>
        <configuration>
            <doclint>none</doclint> <!-- Turn off all checks -->
        </configuration>
        <executions>
            <execution>
                <id>attach-javadocs</id>
                <goals>
                    <goal>jar</goal>
                </goals>
            </execution>
        </executions>
    </plugin>
</plugins>

Но , как правило, не рекомендуется использовать параметр none, поскольку он пропускает все типы проверок. Вместо этого мы должны использовать <doclint>all,-missing</doclint> .

При использовании более ранних версий (до v3.0.0) нам нужно использовать другую настройку:

<plugins>
  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <configuration>
      <additionalparam>-Xdoclint:none</additionalparam>
    </configuration>
  </plugin>
</plugins>

4.2. Грейдл

Мы можем деактивировать DocLint в проектах Gradle с помощью простого скрипта:

if (JavaVersion.current().isJava8Compatible()) {
    allprojects {
        tasks.withType(Javadoc) {
            options.addStringOption('Xdoclint:none', '-quiet')
        }
    }
}

К сожалению, Gradle не поддерживает дополнительные параметры, как это делает Maven в приведенном выше примере, поэтому нам нужно сделать это вручную.

4.3. Муравей

Ant использует дополнительный параметр , как и Maven, поэтому мы можем установить -Xdoclint:none , как показано выше.

5. Вывод

В этой статье мы рассмотрели различные способы использования Java DocLint. Это может помочь нам, когда мы хотим иметь чистый, подверженный ошибкам документ Javadoc.

Для получения дополнительной подробной информации рекомендуется ознакомиться с официальной документацией .