Многие люди знают об источнике maven и артефактах javadoc, но не знают, зачем им их создавать. Я определенно был в этом лагере — я понимаю, почему люди хотят получить эту информацию, но это был относительно неэффективный способ получить ее, поскольку она требует ручной навигации по хранилищу maven.
Затем меня ударила подсказка.
Эти артефакты используются IDE, а не людьми. Если вы используете зависимости maven, IDE достаточно умен, чтобы знать, как найти эти артефакты. Исходный артефакт используется при пошаговом выполнении кода в отладчике — вам больше не нужно явно привязывать исходный код к библиотекам в IDE. Артефакт javadoc используется для автозаполнения и контекстной справки в редакторе.
Ничего из этого не требуется — я был счастлив использовать ‘vi’ много лет — но это определенно повышает вашу производительность, когда вы в основном знаете, что вам нужно, но не совсем уверены в деталях.
Исходные артефакты
Исходные артефакты создавать проще всего. Добавьте плагин, который будет автоматически запускаться как часть стандартной сборки, и все готово. Сборки занимают немного больше времени, но, вероятно, о них не стоит беспокоиться, поскольку вы просто создаете архив из нескольких каталогов.
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
|
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" <build> <plugins> <!-- create source jar --> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-source-plugin</artifactId> <version>2.1.1</version> <executions> <execution> <id>attach-sources</id> <phase>verify</phase> <goals> <!-- produce source artifact for project main sources --> <goal>jar-no-fork</goal> <!-- produce test source artifact for project test sources --> <goal>test-jar-no-fork</goal> </goals> </execution> </executions> </plugin> </plugins> </build></project> |
Javadoc Артефакты
Артефакты Javadoc немного сложнее, так как вы, вероятно, захотите создать сайт, дружественный человеку. По моему опыту, самой большой проблемой является то, что внешние классы были непрозрачными, поскольку для создания необходимых ссылок потребовалось так много усилий. Плагин Maven теперь позаботится об этом для нас!
Для создания этого артефакта требуется значительное количество времени, поэтому, вероятно, вы не захотите делать это каждый раз. Есть два подхода — либо явно указать цель maven, либо привязать ее к пользовательскому профилю, например, «javadoc». В приведенной ниже конфигурации используется пользовательский профиль.
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
|
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" <profiles> <!-- create javadoc --> <profile> <id>javadoc</id> <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> <version>2.9.1</version> <configuration> <detectLinks /> <includeDependencySources>true</includeDependencySources> <dependencySourceIncludes> <dependencySourceInclude>com.invariantproperties.project.student:*</dependencySourceInclude> </dependencySourceIncludes> <!-- heavily used dependencies --> <links> </links> </configuration> <executions> <execution> <id>aggregate</id> <!-- <phase>site</phase> --> <phase>package</phase> <goals> <goal>aggregate</goal> <goal>jar</goal> </goals> </execution> </executions> </plugin> </plugins> </build> <reporting> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> <version>2.9.1</version> <configuration> <!-- Default configuration for all reports --> </configuration> <reportSets> <reportSet> <id>non-aggregate</id> <configuration> <!-- Specific configuration for the non aggregate report --> </configuration> <reports> <report>javadoc</report> </reports> </reportSet> <reportSet> <id>aggregate</id> <configuration> <!-- Specific configuration for the aggregate report --> </configuration> <reports> <report>aggregate</report> </reports> </reportSet> </reportSets> </plugin> </plugins> </reporting> </profile> </profiles></project> |
package-info.java
Наконец, каждый пакет должен иметь файл package-info.java . Это заменяет старый файл package-info.html, но является улучшением, поскольку позволяет использовать аннотации классов. (Он не будет скомпилирован, так как это неверное имя класса.)
Я считаю чрезвычайно полезным включать ссылки на ресурсы, которые помогают мне понять, почему классы выглядят так, как они. Например, пакет метаданных в моем «студенческом» проекте содержит ссылки на мои сообщения в блоге, другие сообщения в блоге, которые я считаю полезными, и даже соответствующее руководство по Oracle. В компании это могут быть ссылки на вики-страницы.
|
01
02
03
04
05
06
07
08
09
10
11
|
/** * Classes that support JPA Criteria Queries for persistent entities. * * @see <a href="http://invariantproperties.com/2013/12/19/project-student-persistence-with-spring-data/">Project Student: Persistence with Spring Data</a> * @see <a href="http://invariantproperties.com/2013/12/29/project-student-jpa-criteria-queries/">Project Student: JPA Criteria Queries</a> * @see <a href="http://www.petrikainulainen.net/programming/spring-framework/spring-data-jpa-tutorial-part-four-jpa-criteria-queries/">Spring Data JPA Tutorial Part Four: JPA Criteria Queries</a> [www.petrikainulainen.net] * @see <a href="http://docs.oracle.com/javaee/6/tutorial/doc/gjitv.html">JEE Tutorial</a> * * @author Bear Giles <[email protected]> */ package com.invariantproperties.project.student.metamodel; |
Исходный код
- Исходный код находится по адресу https://github.com/beargiles/project-student [github] и http://beargiles.github.io/project-student/ [github pages].