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:19:58 UTC
[tomee-site-generator] 04/11: Ability to insert links into javadoc
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 28c0ed841b2d6082a6699401dd48cacc4f6dbead
Author: David Blevins <da...@gmail.com>
AuthorDate: Sat Aug 8 18:05:27 2020 -0700
Ability to insert links into javadoc
---
.../java/org/apache/tomee/website/SeeLinks.java | 50 +++++++++++++++++++++-
.../org/apache/tomee/website/SeeLinksTest.java | 17 ++++++++
.../SeeLinksTest/multipleInserts/after3.java | 2 +-
.../after3.java => noDuplicates/after.java} | 25 ++++++++---
.../after3.java => noDuplicates/before.java} | 26 ++++++++---
5 files changed, 105 insertions(+), 15 deletions(-)
diff --git a/src/main/java/org/apache/tomee/website/SeeLinks.java b/src/main/java/org/apache/tomee/website/SeeLinks.java
index a7231c8..9979361 100644
--- a/src/main/java/org/apache/tomee/website/SeeLinks.java
+++ b/src/main/java/org/apache/tomee/website/SeeLinks.java
@@ -16,6 +16,9 @@
*/
package org.apache.tomee.website;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
/**
* Utility class to insert additional @see links into java source code.
* If no Javadoc exists at the class level, some will be added.
@@ -23,7 +26,52 @@ package org.apache.tomee.website;
public class SeeLinks {
public static String insertHref(final String source, final String link, final String linkText) {
+ final int start = Math.max(source.lastIndexOf("\nimport "), source.indexOf("\npackage "));
+ final int end = min(source.indexOf("\npublic "), source.indexOf("\n@"));
+
+ final String header = source.substring(start, end);
+
+ if (header.contains("/**")) {
+ return updateComment(source, link, linkText, header);
+ } else {
+ return addComment(source, link, linkText, header);
+ }
+ }
+
+ private static int min(final int a, final int b) {
+ if (a == -1) return b;
+ if (b == -1) return a;
+ 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);
+ final String comment = header + "\n/**" + href + "\n */";
+ return source.replace(header, comment);
+ }
+
+ private static String updateComment(final String source, final String link, final String linkText, 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;
+
+ final Pattern commentPattern = Pattern.compile("/\\*\\*(.*\n*)*?\n *\\*/");
+ final Matcher matcher = commentPattern.matcher(header);
+ if (!matcher.find()) return source;
+
+ final String comment = matcher.group(0);
+
+ final String href = href(link, linkText);
+
+ final String updatedComment = comment.replaceFirst("(\n *\\*/)", href + "$1");
+
// TODO
- return source;
+ return source.replace(comment, updatedComment);
+ }
+
+ private static String href(final String link, final String linkText) {
+ final String href = String.format("\n * @see <a href=\"%s\">%s</a>", link, linkText);
+ return href;
}
}
diff --git a/src/test/java/org/apache/tomee/website/SeeLinksTest.java b/src/test/java/org/apache/tomee/website/SeeLinksTest.java
index 64bc931..e740239 100644
--- a/src/test/java/org/apache/tomee/website/SeeLinksTest.java
+++ b/src/test/java/org/apache/tomee/website/SeeLinksTest.java
@@ -78,6 +78,23 @@ public class SeeLinksTest {
* Test we can insert several @see links into the same javadoc
*/
@Test
+ public void noDuplicates() throws IOException {
+ final Scenario scenario = scenario(SeeLinksTest.class, "noDuplicates");
+
+ final String input = scenario.get("before.java");
+
+ final String after1 = SeeLinks.insertHref(input, "http://example.org/orange.html", "Orange Example");
+ assertEquals(scenario.get("after.java"), after1);
+
+ // The second insert should be ignored as it has the same title "Orange Example"
+ final String after2 = SeeLinks.insertHref(after1, "http://example.org/foo.html", "Orange Example");
+ assertEquals(scenario.get("after.java"), after2);
+ }
+
+ /**
+ * Test we can insert several @see links into the same javadoc
+ */
+ @Test
public void hasAnnotations() throws IOException {
final Scenario scenario = scenario(SeeLinksTest.class, "hasAnnotations");
diff --git a/src/test/resources/SeeLinksTest/multipleInserts/after3.java b/src/test/resources/SeeLinksTest/multipleInserts/after3.java
index 932c0cc..a7f36e1 100644
--- a/src/test/resources/SeeLinksTest/multipleInserts/after3.java
+++ b/src/test/resources/SeeLinksTest/multipleInserts/after3.java
@@ -19,7 +19,7 @@ package javax.persistence;
/**
* @see <a href="http://example.org/orange.html">Orange Example</a>
* @see <a href="http://example.org/red.html">Red Sample</a>
- * @see <a href="http://example.org/red.html">yellow</a>
+ * @see <a href="http://example.org/yellow.html">yellow</a>
*/
public enum Shapes {
CIRCLE,
diff --git a/src/test/resources/SeeLinksTest/multipleInserts/after3.java b/src/test/resources/SeeLinksTest/noDuplicates/after.java
similarity index 56%
copy from src/test/resources/SeeLinksTest/multipleInserts/after3.java
copy to src/test/resources/SeeLinksTest/noDuplicates/after.java
index 932c0cc..75f3b52 100644
--- a/src/test/resources/SeeLinksTest/multipleInserts/after3.java
+++ b/src/test/resources/SeeLinksTest/noDuplicates/after.java
@@ -16,13 +16,26 @@
*/
package javax.persistence;
+import java.lang.annotation.Target;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Documented;
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
/**
+ * Specifies that the class is an entity. This annotation is applied to the
+ * entity class.
+ *
+ * @since Java Persistence 1.0
* @see <a href="http://example.org/orange.html">Orange Example</a>
- * @see <a href="http://example.org/red.html">Red Sample</a>
- * @see <a href="http://example.org/red.html">yellow</a>
*/
-public enum Shapes {
- CIRCLE,
- TRIANGLE,
- SQUARE
+public interface Entity {
+
+ /**
+ * (Optional) The entity name. Defaults to the unqualified
+ * name of the entity class. This name is used to refer to the
+ * entity in queries. The name must not be a reserved literal
+ * in the Java Persistence query language.
+ */
+ String name();
}
\ No newline at end of file
diff --git a/src/test/resources/SeeLinksTest/multipleInserts/after3.java b/src/test/resources/SeeLinksTest/noDuplicates/before.java
similarity index 54%
copy from src/test/resources/SeeLinksTest/multipleInserts/after3.java
copy to src/test/resources/SeeLinksTest/noDuplicates/before.java
index 932c0cc..5ffc69c 100644
--- a/src/test/resources/SeeLinksTest/multipleInserts/after3.java
+++ b/src/test/resources/SeeLinksTest/noDuplicates/before.java
@@ -16,13 +16,25 @@
*/
package javax.persistence;
+import java.lang.annotation.Target;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Documented;
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
/**
- * @see <a href="http://example.org/orange.html">Orange Example</a>
- * @see <a href="http://example.org/red.html">Red Sample</a>
- * @see <a href="http://example.org/red.html">yellow</a>
+ * Specifies that the class is an entity. This annotation is applied to the
+ * entity class.
+ *
+ * @since Java Persistence 1.0
*/
-public enum Shapes {
- CIRCLE,
- TRIANGLE,
- SQUARE
+public interface Entity {
+
+ /**
+ * (Optional) The entity name. Defaults to the unqualified
+ * name of the entity class. This name is used to refer to the
+ * entity in queries. The name must not be a reserved literal
+ * in the Java Persistence query language.
+ */
+ String name();
}
\ No newline at end of file