You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tomee.apache.org by db...@apache.org on 2020/08/10 02:20:01 UTC
[tomee-site-generator] 07/11: Support multiple languages in
@example javadoc tags
This is an automated email from the ASF dual-hosted git repository.
dblevins pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tomee-site-generator.git
commit 17d681ddaef73b953a32aa033d4a25055780d472
Author: David Blevins <da...@gmail.com>
AuthorDate: Sun Aug 9 16:10:47 2020 -0700
Support multiple languages in @example javadoc tags
---
.../java/org/apache/tomee/website/Example.java | 34 ++++++++++++++++-----
.../org/apache/tomee/website/ExampleLinks.java | 29 +++++++++++-------
.../java/org/apache/tomee/website/Javadocs.java | 6 +++-
.../org/apache/tomee/website/LearningLinks.java | 5 +++-
.../org/apache/tomee/website/ExampleLinksTest.java | 35 +++++++++++++++++-----
.../ExampleLinksTest/finalClass/after.java | 2 +-
.../ExampleLinksTest/hasAnnotations/after.java | 2 +-
.../ExampleLinksTest/insertHref/after.java | 2 +-
.../ExampleLinksTest/multipleInserts/after1.java | 2 +-
.../ExampleLinksTest/multipleInserts/after2.java | 4 +--
.../ExampleLinksTest/multipleInserts/after3.java | 6 ++--
.../after1.java | 2 +-
.../after2.java | 4 +--
.../after3.java | 6 ++--
.../after1.java => multipleLanguages/before.java} | 3 --
.../ExampleLinksTest/noDuplicates/after.java | 2 +-
.../ExampleLinksTest/noJavadoc/after.java | 2 +-
17 files changed, 99 insertions(+), 47 deletions(-)
diff --git a/src/main/java/org/apache/tomee/website/Example.java b/src/main/java/org/apache/tomee/website/Example.java
index 92560d6..b235728 100644
--- a/src/main/java/org/apache/tomee/website/Example.java
+++ b/src/main/java/org/apache/tomee/website/Example.java
@@ -56,14 +56,12 @@ public class Example {
public void updateDestination(final File examplesDir) { //target/jbake/<tomeeBranch>
-
-
- if (this.language.equalsIgnoreCase("")) {
+ if (this.language.equalsIgnoreCase("") || this.language.equalsIgnoreCase("en")) {
File languageDir = new File(examplesDir + File.separator + "examples");
if (!languageDir.exists()) {
languageDir.mkdirs(); //tomee8.0/examples
}
- this.setDestReadme(new File(examplesDir+File.separator+"examples", this.getName() + "." + this.getExt()));
+ this.setDestReadme(new File(examplesDir + File.separator + "examples", this.getName() + "." + this.getExt()));
} else {
File languageDir = new File(examplesDir + File.separator + getLanguage() + File.separator + "examples");
@@ -108,10 +106,22 @@ public class Example {
final String exampleName = readme.getParentFile().getName();
final String language = getLanguage(readme);
- if (exampleName.equalsIgnoreCase("")) {
- return new Example(readme, exampleName, ext, exampleName + ".html", "Example");
- } else {
+ if (language.equalsIgnoreCase("") || language.equalsIgnoreCase("en")) {
+
+ return new Example(readme, exampleName, ext, exampleName + ".html", "Examples", "en");
+
+ } else if (language.equalsIgnoreCase("es")) {
+
return new Example(readme, exampleName, ext, exampleName + ".html", "Ejemplos", language);
+
+ } else if (language.equalsIgnoreCase("pt")) {
+
+ return new Example(readme, exampleName, ext, exampleName + ".html", "Exemplos", language);
+
+ } else {
+
+ return new Example(readme, exampleName, ext, exampleName + ".html", "Examples", language);
+
}
}
@@ -128,4 +138,14 @@ public class Example {
public static String getExtension(final File readme) {
return readme.getName().replaceFirst("[^.]+\\.", "");
}
+
+ @Override
+ public String toString() {
+ return "Example{" +
+ "name='" + name + '\'' +
+ ", language='" + language + '\'' +
+ ", category='" + category + '\'' +
+ ", destReadme=" + destReadme +
+ '}';
+ }
}
diff --git a/src/main/java/org/apache/tomee/website/ExampleLinks.java b/src/main/java/org/apache/tomee/website/ExampleLinks.java
index 0044a7a..126b51a 100644
--- a/src/main/java/org/apache/tomee/website/ExampleLinks.java
+++ b/src/main/java/org/apache/tomee/website/ExampleLinks.java
@@ -23,6 +23,7 @@ import org.tomitribe.util.Join;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
+import java.util.stream.Stream;
/**
* Utility class to insert additional @example links into java source code.
@@ -33,16 +34,16 @@ import java.util.List;
*/
public class ExampleLinks {
- public static String insertHref(final String source, final String link, final String linkText) {
+ public static String insertHref(final String source, final String link, final String linkText, final String language) {
final int start = Math.max(source.lastIndexOf("\nimport "), source.indexOf("\npackage "));
final int end = min(min(source.indexOf("\npublic "), source.indexOf("\n@")), source.indexOf("\nfinal"));
final String header = source.substring(start, end);
if (header.contains("/**")) {
- return updateComment(source, link, linkText, header);
+ return updateComment(source, link, linkText, language, header);
} else {
- return addComment(source, link, linkText, header);
+ return addComment(source, link, linkText, language, header);
}
}
@@ -55,17 +56,17 @@ public class ExampleLinks {
return Math.min(a, b);
}
- private static String addComment(final String source, final String link, final String linkText, final String header) {
- final String href = href(link, linkText);
+ private static String addComment(final String source, final String link, final String linkText, final String language, final String header) {
+ final String href = href(link, linkText, language);
final String comment = header + "\n/**\n" + href + "\n */";
return source.replace(header, comment);
}
- private static String updateComment(final String source, final String link, final String linkText, final String header) {
+ private static String updateComment(final String source, final String link, final String linkText, final String language, final String header) {
/*
* If we already have a link to this example, don't add it again
*/
- if (header.contains(String.format(">%s</a>", linkText))) return source;
+ if (exists(linkText, language, header)) return source;
final StreamLexer lexer = new StreamLexer(IO.read(header));
final String comment;
@@ -75,7 +76,7 @@ public class ExampleLinks {
throw new IllegalStateException(e);
}
- final String href = href(link, linkText);
+ final String href = href(link, linkText, language);
final List<String> lines = new ArrayList<>(Arrays.asList(comment.split("\n")));
lines.add(lines.size() - 1, href);
@@ -86,8 +87,16 @@ public class ExampleLinks {
return source.replace(comment, updatedComment);
}
- private static String href(final String link, final String linkText) {
- final String href = String.format(" * @example <a href=\"%s\">%s</a>", link, linkText);
+ private static boolean exists(final String linkText, final String language, final String header) {
+ final long count = Stream.of(header.split("\n"))
+ .filter(s -> s.contains("@example." + language))
+ .filter(s -> s.contains(">" + linkText + "<"))
+ .count();
+ return count > 0;
+ }
+
+ private static String href(final String link, final String linkText, final String language) {
+ final String href = String.format(" * @example.%s <a href=\"%s\">%s</a>", language, link, linkText);
return href;
}
}
diff --git a/src/main/java/org/apache/tomee/website/Javadocs.java b/src/main/java/org/apache/tomee/website/Javadocs.java
index ae187d9..01226d8 100644
--- a/src/main/java/org/apache/tomee/website/Javadocs.java
+++ b/src/main/java/org/apache/tomee/website/Javadocs.java
@@ -93,7 +93,11 @@ public class Javadocs {
final ProcessBuilder cmd = new ProcessBuilder(
getJavadocCommand().getAbsolutePath(),
"-tag",
- "example:a:Examples:",
+ "example.en:a:Examples (en):",
+ "-tag",
+ "example.es:a:Examples (es):",
+ "-tag",
+ "example.pt:a:Examples (pt):",
"-sourcepath",
javaSources.getAbsolutePath(),
"-d",
diff --git a/src/main/java/org/apache/tomee/website/LearningLinks.java b/src/main/java/org/apache/tomee/website/LearningLinks.java
index aa0f488..aafff09 100644
--- a/src/main/java/org/apache/tomee/website/LearningLinks.java
+++ b/src/main/java/org/apache/tomee/website/LearningLinks.java
@@ -98,6 +98,9 @@ public class LearningLinks {
addSeeLink(sources.get(api), example);
}
+ // Don't add any links if the source format is markdown
+ if (!example.getSrcReadme().getName().endsWith(".adoc")) continue;
+
// Add APIs Used links to Example
addApisUsed(example, apisUsed, sources, source);
@@ -211,7 +214,7 @@ public class LearningLinks {
// Update the source contents to include an href link
- final String modified = ExampleLinks.insertHref(content, link, name);
+ final String modified = ExampleLinks.insertHref(content, link, name, example.getLanguage());
// Overwrite the source with the newly linked version
IO.copy(IO.read(modified), javadocSource.getSourceFile());
diff --git a/src/test/java/org/apache/tomee/website/ExampleLinksTest.java b/src/test/java/org/apache/tomee/website/ExampleLinksTest.java
index 3b15094..5b53d1d 100644
--- a/src/test/java/org/apache/tomee/website/ExampleLinksTest.java
+++ b/src/test/java/org/apache/tomee/website/ExampleLinksTest.java
@@ -36,7 +36,7 @@ public class ExampleLinksTest {
final String input = scenario.get("before.java");
- final String actual = ExampleLinks.insertHref(input, "http://example.org/orange.html", "Orange Example");
+ final String actual = ExampleLinks.insertHref(input, "http://example.org/orange.html", "Orange Example", "en");
assertEquals(scenario.get("after.java"), actual);
}
@@ -50,7 +50,7 @@ public class ExampleLinksTest {
final String input = scenario.get("before.java");
- final String actual = ExampleLinks.insertHref(input, "http://example.org/orange.html", "Orange Example");
+ final String actual = ExampleLinks.insertHref(input, "http://example.org/orange.html", "Orange Example", "en");
assertEquals(scenario.get("after.java"), actual);
}
@@ -64,13 +64,32 @@ public class ExampleLinksTest {
final String input = scenario.get("before.java");
- final String after1 = ExampleLinks.insertHref(input, "http://example.org/orange.html", "Orange Example");
+ final String after1 = ExampleLinks.insertHref(input, "http://example.org/orange.html", "Orange Example", "en");
assertEquals(scenario.get("after1.java"), after1);
- final String after2 = ExampleLinks.insertHref(after1, "http://example.org/red.html", "Red Sample");
+ final String after2 = ExampleLinks.insertHref(after1, "http://example.org/red.html", "Red Sample", "en");
assertEquals(scenario.get("after2.java"), after2);
- final String after3 = ExampleLinks.insertHref(after2, "http://example.org/yellow.html", "yellow");
+ final String after3 = ExampleLinks.insertHref(after2, "http://example.org/yellow.html", "yellow", "en");
+ assertEquals(scenario.get("after3.java"), after3);
+ }
+
+ /**
+ * Test we can insert several @see links into the same javadoc
+ */
+ @Test
+ public void multipleLanguages() throws IOException {
+ final Scenario scenario = scenario(ExampleLinksTest.class, "multipleLanguages");
+
+ final String input = scenario.get("before.java");
+
+ final String after1 = ExampleLinks.insertHref(input, "http://example.org/orange.html", "Orange Example", "en");
+ assertEquals(scenario.get("after1.java"), after1);
+
+ final String after2 = ExampleLinks.insertHref(after1, "http://example.org/es/orange.html", "Orange Example", "es");
+ assertEquals(scenario.get("after2.java"), after2);
+
+ final String after3 = ExampleLinks.insertHref(after2, "http://example.org/pt/orange.html", "Orange Example", "pt");
assertEquals(scenario.get("after3.java"), after3);
}
@@ -83,11 +102,11 @@ public class ExampleLinksTest {
final String input = scenario.get("before.java");
- final String after1 = ExampleLinks.insertHref(input, "http://example.org/orange.html", "Orange Example");
+ final String after1 = ExampleLinks.insertHref(input, "http://example.org/orange.html", "Orange Example", "en");
assertEquals(scenario.get("after.java"), after1);
// The second insert should be ignored as it has the same title "Orange Example"
- final String after2 = ExampleLinks.insertHref(after1, "http://example.org/foo.html", "Orange Example");
+ final String after2 = ExampleLinks.insertHref(after1, "http://example.org/foo.html", "Orange Example", "en");
assertEquals(scenario.get("after.java"), after2);
}
@@ -100,7 +119,7 @@ public class ExampleLinksTest {
final String input = scenario.get("before.java");
- final String actual = ExampleLinks.insertHref(input, "http://example.org/orange.html", "Orange Example");
+ final String actual = ExampleLinks.insertHref(input, "http://example.org/orange.html", "Orange Example", "en");
assertEquals(scenario.get("after.java"), actual);
}
diff --git a/src/test/resources/ExampleLinksTest/finalClass/after.java b/src/test/resources/ExampleLinksTest/finalClass/after.java
index e91e524..de8c953 100644
--- a/src/test/resources/ExampleLinksTest/finalClass/after.java
+++ b/src/test/resources/ExampleLinksTest/finalClass/after.java
@@ -27,7 +27,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* entity class.
*
* @since Java Persistence 1.0
- * @example <a href="http://example.org/orange.html">Orange Example</a>
+ * @example.en <a href="http://example.org/orange.html">Orange Example</a>
*/
final public interface Entity {
diff --git a/src/test/resources/ExampleLinksTest/hasAnnotations/after.java b/src/test/resources/ExampleLinksTest/hasAnnotations/after.java
index ceefe62..e0e296d 100644
--- a/src/test/resources/ExampleLinksTest/hasAnnotations/after.java
+++ b/src/test/resources/ExampleLinksTest/hasAnnotations/after.java
@@ -23,7 +23,7 @@ import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
- * @example <a href="http://example.org/orange.html">Orange Example</a>
+ * @example.en <a href="http://example.org/orange.html">Orange Example</a>
*/
@Documented
@Target(TYPE)
diff --git a/src/test/resources/ExampleLinksTest/insertHref/after.java b/src/test/resources/ExampleLinksTest/insertHref/after.java
index ef26259..7f9fa3b 100644
--- a/src/test/resources/ExampleLinksTest/insertHref/after.java
+++ b/src/test/resources/ExampleLinksTest/insertHref/after.java
@@ -27,7 +27,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* entity class.
*
* @since Java Persistence 1.0
- * @example <a href="http://example.org/orange.html">Orange Example</a>
+ * @example.en <a href="http://example.org/orange.html">Orange Example</a>
*/
public interface Entity {
diff --git a/src/test/resources/ExampleLinksTest/multipleInserts/after1.java b/src/test/resources/ExampleLinksTest/multipleInserts/after1.java
index 0aa811d..f5c8299 100644
--- a/src/test/resources/ExampleLinksTest/multipleInserts/after1.java
+++ b/src/test/resources/ExampleLinksTest/multipleInserts/after1.java
@@ -17,7 +17,7 @@
package javax.persistence;
/**
- * @example <a href="http://example.org/orange.html">Orange Example</a>
+ * @example.en <a href="http://example.org/orange.html">Orange Example</a>
*/
public enum Shapes {
CIRCLE,
diff --git a/src/test/resources/ExampleLinksTest/multipleInserts/after2.java b/src/test/resources/ExampleLinksTest/multipleInserts/after2.java
index 7471d5e..f28915a 100644
--- a/src/test/resources/ExampleLinksTest/multipleInserts/after2.java
+++ b/src/test/resources/ExampleLinksTest/multipleInserts/after2.java
@@ -17,8 +17,8 @@
package javax.persistence;
/**
- * @example <a href="http://example.org/orange.html">Orange Example</a>
- * @example <a href="http://example.org/red.html">Red Sample</a>
+ * @example.en <a href="http://example.org/orange.html">Orange Example</a>
+ * @example.en <a href="http://example.org/red.html">Red Sample</a>
*/
public enum Shapes {
CIRCLE,
diff --git a/src/test/resources/ExampleLinksTest/multipleInserts/after3.java b/src/test/resources/ExampleLinksTest/multipleInserts/after3.java
index 5eb5e0d..c332478 100644
--- a/src/test/resources/ExampleLinksTest/multipleInserts/after3.java
+++ b/src/test/resources/ExampleLinksTest/multipleInserts/after3.java
@@ -17,9 +17,9 @@
package javax.persistence;
/**
- * @example <a href="http://example.org/orange.html">Orange Example</a>
- * @example <a href="http://example.org/red.html">Red Sample</a>
- * @example <a href="http://example.org/yellow.html">yellow</a>
+ * @example.en <a href="http://example.org/orange.html">Orange Example</a>
+ * @example.en <a href="http://example.org/red.html">Red Sample</a>
+ * @example.en <a href="http://example.org/yellow.html">yellow</a>
*/
public enum Shapes {
CIRCLE,
diff --git a/src/test/resources/ExampleLinksTest/multipleInserts/after1.java b/src/test/resources/ExampleLinksTest/multipleLanguages/after1.java
similarity index 92%
copy from src/test/resources/ExampleLinksTest/multipleInserts/after1.java
copy to src/test/resources/ExampleLinksTest/multipleLanguages/after1.java
index 0aa811d..f5c8299 100644
--- a/src/test/resources/ExampleLinksTest/multipleInserts/after1.java
+++ b/src/test/resources/ExampleLinksTest/multipleLanguages/after1.java
@@ -17,7 +17,7 @@
package javax.persistence;
/**
- * @example <a href="http://example.org/orange.html">Orange Example</a>
+ * @example.en <a href="http://example.org/orange.html">Orange Example</a>
*/
public enum Shapes {
CIRCLE,
diff --git a/src/test/resources/ExampleLinksTest/multipleInserts/after2.java b/src/test/resources/ExampleLinksTest/multipleLanguages/after2.java
similarity index 85%
copy from src/test/resources/ExampleLinksTest/multipleInserts/after2.java
copy to src/test/resources/ExampleLinksTest/multipleLanguages/after2.java
index 7471d5e..fec0104 100644
--- a/src/test/resources/ExampleLinksTest/multipleInserts/after2.java
+++ b/src/test/resources/ExampleLinksTest/multipleLanguages/after2.java
@@ -17,8 +17,8 @@
package javax.persistence;
/**
- * @example <a href="http://example.org/orange.html">Orange Example</a>
- * @example <a href="http://example.org/red.html">Red Sample</a>
+ * @example.en <a href="http://example.org/orange.html">Orange Example</a>
+ * @example.es <a href="http://example.org/es/orange.html">Orange Example</a>
*/
public enum Shapes {
CIRCLE,
diff --git a/src/test/resources/ExampleLinksTest/multipleInserts/after3.java b/src/test/resources/ExampleLinksTest/multipleLanguages/after3.java
similarity index 79%
copy from src/test/resources/ExampleLinksTest/multipleInserts/after3.java
copy to src/test/resources/ExampleLinksTest/multipleLanguages/after3.java
index 5eb5e0d..5c6c19e 100644
--- a/src/test/resources/ExampleLinksTest/multipleInserts/after3.java
+++ b/src/test/resources/ExampleLinksTest/multipleLanguages/after3.java
@@ -17,9 +17,9 @@
package javax.persistence;
/**
- * @example <a href="http://example.org/orange.html">Orange Example</a>
- * @example <a href="http://example.org/red.html">Red Sample</a>
- * @example <a href="http://example.org/yellow.html">yellow</a>
+ * @example.en <a href="http://example.org/orange.html">Orange Example</a>
+ * @example.es <a href="http://example.org/es/orange.html">Orange Example</a>
+ * @example.pt <a href="http://example.org/pt/orange.html">Orange Example</a>
*/
public enum Shapes {
CIRCLE,
diff --git a/src/test/resources/ExampleLinksTest/multipleInserts/after1.java b/src/test/resources/ExampleLinksTest/multipleLanguages/before.java
similarity index 91%
copy from src/test/resources/ExampleLinksTest/multipleInserts/after1.java
copy to src/test/resources/ExampleLinksTest/multipleLanguages/before.java
index 0aa811d..9321f32 100644
--- a/src/test/resources/ExampleLinksTest/multipleInserts/after1.java
+++ b/src/test/resources/ExampleLinksTest/multipleLanguages/before.java
@@ -16,9 +16,6 @@
*/
package javax.persistence;
-/**
- * @example <a href="http://example.org/orange.html">Orange Example</a>
- */
public enum Shapes {
CIRCLE,
TRIANGLE,
diff --git a/src/test/resources/ExampleLinksTest/noDuplicates/after.java b/src/test/resources/ExampleLinksTest/noDuplicates/after.java
index ef26259..7f9fa3b 100644
--- a/src/test/resources/ExampleLinksTest/noDuplicates/after.java
+++ b/src/test/resources/ExampleLinksTest/noDuplicates/after.java
@@ -27,7 +27,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* entity class.
*
* @since Java Persistence 1.0
- * @example <a href="http://example.org/orange.html">Orange Example</a>
+ * @example.en <a href="http://example.org/orange.html">Orange Example</a>
*/
public interface Entity {
diff --git a/src/test/resources/ExampleLinksTest/noJavadoc/after.java b/src/test/resources/ExampleLinksTest/noJavadoc/after.java
index 9ed617c..86498dd 100644
--- a/src/test/resources/ExampleLinksTest/noJavadoc/after.java
+++ b/src/test/resources/ExampleLinksTest/noJavadoc/after.java
@@ -17,7 +17,7 @@
package javax.persistence;
/**
- * @example <a href="http://example.org/orange.html">Orange Example</a>
+ * @example.en <a href="http://example.org/orange.html">Orange Example</a>
*/
public @interface Entity {