Skip to content

Commit 5cfe65d

Browse files
author
Nicolai Parlog
committed
Present more Javadoc snippet features
1 parent 825ca99 commit 5cfe65d

File tree

5 files changed

+245
-7
lines changed

5 files changed

+245
-7
lines changed

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,7 @@ Most are show-cased in these posts, though:
125125

126126
## JVM & Tooling
127127

128+
* ⑱ external snippets in Javadoc: [referencing class](src/main/java/org/codefx/demo/java18/jvm/javadoc/SnippetDocs.java), [referenced demo class](src/demo/java/SnippetDocsDemo.java), and [configuration](pom.xml) ([feature introduction](https://nipafx.dev/inside-java-newscast-20/), [Maven how-to](https://nipafx.dev/javadoc-snippets-maven/), [JEP 413](http://openjdk.java.net/jeps/413))
128129
* ⑬⑫⑩ [application class-dara sharing](app-cds.sh) ([article](http://blog.codefx.org/java/application-class-data-sharing/), [JEP 310](http://openjdk.java.net/jeps/310), [JEP 341](http://openjdk.java.net/jeps/341), [JEP 350](http://openjdk.java.net/jeps/350))
129130
* ⑪ [single-source-file execution](src/main/java/org/codefx/demo/java11/jvm/script) and scripting: run [the script](echo) with `cat echo-haiku.txt | ./echo` ([article](http://blog.codefx.org/java/scripting-java-shebang/), [JEP 330](https://openjdk.java.net/jeps/330))
130131
* ⑨ multi-release JARs: [classes](src/main/java/org/codefx/demo/java9/internal/multi_release) and [the script](multi-release.sh) ([JEP 238](http://openjdk.java.net/jeps/238))

‎pom.xml

Lines changed: 55 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -102,11 +102,17 @@
102102
<artifactId>maven-javadoc-plugin</artifactId>
103103
<version>3.3.1</version>
104104
<configuration>
105-
<release>${maven.compiler.source}</release>
106105
<subpackages>org.codefx.demo.java18.jvm.javadoc</subpackages>
107-
<!-- set the demo folder as snippet-path to find snippet files there -->
108-
<additionalOptions>--snippet-path ${project.basedir}/src/demo/java</additionalOptions>
109106
</configuration>
107+
<executions>
108+
<execution>
109+
<id>create-javadoc</id>
110+
<phase>package</phase>
111+
<goals>
112+
<goal>javadoc</goal>
113+
</goals>
114+
</execution>
115+
</executions>
110116
</plugin>
111117
<plugin>
112118
<artifactId>maven-dependency-plugin</artifactId>
@@ -136,4 +142,50 @@
136142
</plugins>
137143
</build>
138144

145+
<profiles>
146+
<!-- on JDK 17 and before, configure Javadoc to ignore (unknown) @snippet tags -->
147+
<profile>
148+
<id>java-17-</id>
149+
<activation>
150+
<jdk>(,17]</jdk>
151+
</activation>
152+
<build>
153+
<plugins>
154+
<plugin>
155+
<artifactId>maven-javadoc-plugin</artifactId>
156+
<configuration>
157+
<tags>
158+
<tag>
159+
<name>snippet</name>
160+
<placement>x</placement>
161+
</tag>
162+
</tags>
163+
</configuration>
164+
</plugin>
165+
</plugins>
166+
</build>
167+
</profile>
168+
<!-- on JDK 18 and later, configure Javadoc with snippet path to demo source tree -->
169+
<profile>
170+
<id>java-18+</id>
171+
<activation>
172+
<jdk>[18,)</jdk>
173+
</activation>
174+
<build>
175+
<plugins>
176+
<plugin>
177+
<artifactId>maven-javadoc-plugin</artifactId>
178+
<configuration>
179+
<!-- set the demo and folders as snippet-path to find snippet files there -->
180+
<additionalOptions>
181+
<additionalOption>--snippet-path ${project.basedir}/src/demo/java${path.separator}${project.basedir}/src/demo/css</additionalOption>
182+
<additionalOption>--add-stylesheet ${project.basedir}/src/demo/css/javadoc-highlight.css</additionalOption>
183+
</additionalOptions>
184+
</configuration>
185+
</plugin>
186+
</plugins>
187+
</build>
188+
</profile>
189+
</profiles>
190+
139191
</project>

‎src/demo/css/javadoc-highlight.css

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
@import url('https://fonts.googleapis.com/css2?family=Creepster&display=swap');
2+
3+
.scary {
4+
font-family: "Creepster", cursive;
5+
font-size: 2em;
6+
line-height: 1.2;
7+
color: #8a0303;
8+
background-color: unset;
9+
}
10+
11+
.scary::after {
12+
content: "👻";
13+
background-color: #8a0303;
14+
padding: 0.5em 0.5em 0.25em;
15+
border-radius: 0.25em;
16+
margin: 0 0.5em 0 0.25em;
17+
}

‎src/demo/java/SnippetDocsDemo.java

Lines changed: 113 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,129 @@
11
package org.codefx.demo.java18.jvm.javadoc;
22

3+
import org.junit.jupiter.api.Nested;
34
import org.junit.jupiter.api.Test;
45

5-
import static org.junit.jupiter.api.Assertions.assertNotNull;
6+
import java.util.List;
67

78
class SnippetDocsDemo {
89

910
@Test
1011
void constructorDemo() {
1112
// @start region="constructor"
12-
// How to call the parameterless constructor
13+
// How to call the parameterless constructor:
1314
SnippetDocs docs = new SnippetDocs();
1415
// @end
1516

16-
assertNotNull(docs);
17+
// assert correct behavior...
18+
}
19+
20+
@Nested
21+
class HighlightDemo {
22+
23+
@Test
24+
void substringDemo() {
25+
// @start region="highlight-substring"
26+
// it's similar to `new Object()`:
27+
SnippetDocs docs = new SnippetDocs(); // @highlight substring="new SnippetDocs()"
28+
// @end
29+
}
30+
31+
@Test
32+
void regexDemo() {
33+
// @start region="highlight-regex"
34+
// it's similar to `new Object()`:
35+
SnippetDocs docs = new SnippetDocs(); // @highlight regex="SnippetDocs[^\s]*"
36+
// @end
37+
}
38+
39+
@Test
40+
void singleDemo() {
41+
// @start region="highlight-single"
42+
// it's similar to `new Object()`:
43+
SnippetDocs docs = new SnippetDocs(); // @highlight substring="new"
44+
// @end
45+
}
46+
47+
@Test
48+
void regionDemo() {
49+
// @start region="highlight-region" @highlight region substring="new"
50+
// it's similar to `new Object()`:
51+
SnippetDocs docs = new SnippetDocs();
52+
// @end @end
53+
}
54+
55+
@Test
56+
void boldDemo() {
57+
// @start region="highlight-bold"
58+
// it's similar to `new Object()`:
59+
SnippetDocs docs = new SnippetDocs(); // @highlight substring="new SnippetDocs()" type="bold"
60+
// @end
61+
}
62+
63+
@Test
64+
void italicDemo() {
65+
// @start region="highlight-italic"
66+
// it's similar to `new Object()`:
67+
SnippetDocs docs = new SnippetDocs(); // @highlight substring="new SnippetDocs()" type="italic"
68+
// @end
69+
}
70+
71+
@Test
72+
void highlightedDemo() {
73+
// @start region="highlight-highlighted"
74+
// it's similar to `new Object()`:
75+
SnippetDocs docs = new SnippetDocs(); // @highlight substring="new SnippetDocs()" type="highlight"
76+
// @end
77+
}
78+
79+
@Test
80+
void customHighlightedDemo() {
81+
// @start region="highlight-scary"
82+
// styled with src/demo/css/javadoc-highlight.css
83+
SnippetDocs docs = new SnippetDocs(); // @highlight substring="new SnippetDocs()" type="scary"
84+
// @end
85+
}
86+
87+
}
88+
89+
@Nested
90+
class ReplaceDemo {
91+
92+
@Test
93+
void substringDemo() {
94+
// @start region="replace-substring"
95+
// it's similar to `new Object()`:
96+
SnippetDocs docs = new SnippetDocs(); // @replace substring="SnippetDocs docs" replacement="..."
97+
// @end
98+
}
99+
100+
}
101+
102+
@Nested
103+
class LinkDemo {
104+
105+
@Test
106+
void regexDemo() {
107+
// @start region="link-regex" @link region regex="new Object\(\)" target="Object#Object()"
108+
// it's similar to `new Object()`:
109+
SnippetDocs docs = new SnippetDocs();
110+
// @end @end
111+
}
112+
113+
}
114+
115+
@Nested
116+
class InlineCheckDemo {
117+
118+
@Test
119+
void demo() {
120+
// for hybrid snippets (inline and an external file), the @start comment needs to end with
121+
// a semicolon or the snippet starts with a spurious newline
122+
// @start region="inline-check":
123+
List<String> yay = List.of("Don't", "have to", "escape <>&", "!");
124+
// @end
125+
}
126+
17127
}
18128

19129
}

‎src/main/java/org/codefx/demo/java18/jvm/javadoc/SnippetDocs.java

Lines changed: 59 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,65 @@
22

33
/**
44
* This class has a constructor and here's how you call it:
5-
* {@snippet file="SnippetDocsDemo.java" region="constructor"}
5+
* {@snippet class="SnippetDocsDemo" region="constructor"}
6+
*
7+
* <h2>Highlighting</h2>
8+
*
9+
* With highlights (matching by substring):
10+
* {@snippet class="SnippetDocsDemo" region="highlight-substring"}
11+
*
12+
* With highlights (matching by regex):
13+
* {@snippet class="SnippetDocsDemo" region="highlight-regex"}
14+
*
15+
* With highlights (in a single line):
16+
* {@snippet class="SnippetDocsDemo" region="highlight-single"}
17+
*
18+
* With highlights (in the entire region):
19+
* {@snippet class="SnippetDocsDemo" region="highlight-region"}
20+
*
21+
* With highlights (in bold):
22+
* {@snippet class="SnippetDocsDemo" region="highlight-bold"}
23+
*
24+
* With highlights (in italic):
25+
* {@snippet class="SnippetDocsDemo" region="highlight-italic"}
26+
*
27+
* With highlights (highlighted):
28+
* {@snippet class="SnippetDocsDemo" region="highlight-highlighted"}
29+
*
30+
* With highlights (customized highlighted):
31+
* {@snippet class="SnippetDocsDemo" region="highlight-scary"}
32+
*
33+
* <h2>Replacing</h2>
34+
*
35+
* Replacing code (matching by substring):
36+
* {@snippet class="SnippetDocsDemo" region="replace-substring"}
37+
*
38+
* <h2>Linking</h2>
39+
*
40+
* Linking words (matching by regex):
41+
* {@snippet class="SnippetDocsDemo" region="link-regex"}
42+
*
43+
* <h2>Other files</h2>
44+
*
45+
* That CSS from earlier:
46+
* {@snippet file="javadoc-highlight.css"}
47+
*
48+
* <h2>HTML IDs</h2>
49+
*
50+
* That CSS from earlier:
51+
* {@snippet file="javadoc-highlight.css" id="highlighted-style"}
52+
*
53+
* <h2>Inline</h2>
54+
*
55+
* Code in Javadoc:
56+
* {@snippet :
57+
* List<String> yay = List.of("Don't", "have to", "escape <>&");
58+
* }
59+
*
60+
* Code in Javadoc with check
61+
* {@snippet class="SnippetDocsDemo" region="inline-check" :
62+
* List<String> yay = List.of("Don't", "have to", "escape <>&", "!");
63+
* }
664
*/
765
public class SnippetDocs {
866

0 commit comments

Comments
 (0)