Это философская или этическая команда. Очень общий. Это что-то вроде «быстро провалиться». Причина, по которой это пришло мне в голову, заключается в том, что я хотел скомпилировать и выпустить License3j с использованием Java 8, а JavaDoc отказался от компиляции во время сборки выпуска.
Этот пакет представляет собой простой менеджер лицензий, имеющий определенную базу пользователей, которая требует, чтобы я не отставал от новых версий BouncyCastle. Сам по себе пакет криптографии не должен быть устаревшим, и программам рекомендуется использовать последнюю версию, чтобы избежать проблем безопасности. Когда я выполнил mvn release:prepare я получил много ошибок:
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
|
[ERROR] * <p>[ERROR] ^[ERROR] /Users/verhasp/github/License3j/src/main/java/License3j.java:132: error: unexpected end tag: </p>[ERROR] * </p>[ERROR] ^[ERROR] /Users/verhasp/github/License3j/src/main/java/License3j.java:134: warning: no @param for args[ERROR] public static void main(String[] args) throws Exception {[ERROR] ^[ERROR] /Users/verhasp/github/License3j/src/main/java/License3j.java:134: warning: no @throws for java.lang.Exception[ERROR] public static void main(String[] args) throws Exception {[ERROR] ^[ERROR] /Users/verhasp/github/License3j/src/main/java/com/verhas/licensor/ExtendedLicense.java:73: warning: no @param for expiryDate[ERROR] public void setExpiry(final Date expiryDate) {[ERROR] ^[ERROR] /Users/verhasp/github/License3j/src/main/java/com/verhas/licensor/License.java:196: warning: no description for @throws[ERROR] * @throws IOException[ERROR] ^[ERROR] /Users/verhasp/github/License3j/src/main/java/com/verhas/licensor/License.java:246: warning: no description for @throws |
Новый JavaDoc хочет вас DIR
Ошибки есть, потому что документ Java License3j немного небрежно. Извините, ребята, я создал код много лет назад, и, честно говоря, это не только документ Java, который можно улучшить. Фактически, один из модульных тестов зависит от сети и доступности GitHub. (Больше нет, хотя, я это исправил.)
Новая версия Java 8 очень строго относится к JavaDoc. Как вы можете видеть на странице « Улучшения в Javadoc, Java SE 8 » ORACLE:
Инструмент javadoc теперь поддерживает проверку содержимого комментариев javadoc на наличие проблем, которые могут привести к различным проблемам, таким как недопустимый HTML или проблемы доступности, в файлах, созданных javadoc. Эта функция включена по умолчанию, а также может управляться с помощью новой опции -Xdoclint. Для получения более подробной информации смотрите вывод команды «javadoc -X». Эта функция также доступна в javac, хотя по умолчанию она там не включена.
Чтобы заставить релиз работать, у меня был выбор исправить JavaDoc или использовать конфигурацию
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
|
<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> <version>2.9</version> <executions> <execution> <id>attach-javadocs</id> <goals> <goal>jar</goal> </goals> <configuration> <additionalparam>-Xdoclint:none</additionalparam> </configuration> </execution> </executions></plugin> |
в pom.xml . (Источник — переполнение стека .)
Но вы просто не будете DIR
Вы можете легко представить, что вы выберете второй вариант, когда вы находитесь под давлением времени. Вы исправляете проблему, изменяя ваш pom.xml или другую конфигурацию сборки, и забываете об этом.
Но вы продолжаете думать о том, почему это так? Почему новый инструмент строг по умолчанию? Это хороший выбор? Будет ли это побуждать людей создавать лучшие JavaDoc?
(На данный момент я предполагаю, что целью нового поведения было побудить программистов создавать лучшую документацию по JavaDoc, а не просто раздражать нас.)
Я немного подозреваю, что одного этого будет достаточно для улучшения документации. Программисты будут:
- Выключите опцию ворса.
- Удалить JavaDoc из источника.
- Напишите какое-нибудь описание, которое будет принимать Java 8, но в целом оно бессмысленно
или некоторые из них просто напишут правильный документ Java. Некоторым из них, которые все равно хорошо это писали, поможет новая строгость. Сколько нас? 1% или 2%? Остальные увидят это как кнут и попытаются избежать. Нам нужна морковь вместо этого. Эй, зайчики! Где морковь?
| Ссылка: | Если вы делаете это, сделайте это прямо у нашего партнера JCG Питера Верхаса в блоге Java Deep . |