You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by da...@apache.org on 2018/08/22 10:24:43 UTC
[camel] 01/02: CAMEL-12743: apt compiler plugin should generate
documentation without javadoc inlined links,
and fixed when they refer to fields via the # syntax.
This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel.git
commit 88ec23a15e333ae2003d560850915a84035befec
Author: Claus Ibsen <cl...@gmail.com>
AuthorDate: Wed Aug 22 09:42:55 2018 +0200
CAMEL-12743: apt compiler plugin should generate documentation without javadoc inlined links, and fixed when they refer to fields via the # syntax.
---
.../camel/tools/apt/helper/JsonSchemaHelper.java | 14 +++-
.../camel/tools/apt/JsonSchemaHelperTest.java | 84 ++++++++++++++++++++++
2 files changed, 96 insertions(+), 2 deletions(-)
diff --git a/tooling/apt/src/main/java/org/apache/camel/tools/apt/helper/JsonSchemaHelper.java b/tooling/apt/src/main/java/org/apache/camel/tools/apt/helper/JsonSchemaHelper.java
index ae0ed37..6f4c7ce 100644
--- a/tooling/apt/src/main/java/org/apache/camel/tools/apt/helper/JsonSchemaHelper.java
+++ b/tooling/apt/src/main/java/org/apache/camel/tools/apt/helper/JsonSchemaHelper.java
@@ -34,7 +34,7 @@ import org.json.simple.Jsoner;
*/
public final class JsonSchemaHelper {
- private static final String VALID_CHARS = ".,-='/\\!&%():;";
+ private static final String VALID_CHARS = ".,-='/\\!&%():;#";
private JsonSchemaHelper() {
}
@@ -263,6 +263,15 @@ public final class JsonSchemaHelper {
for (String line : lines) {
line = line.trim();
+ if (line.startsWith("**")) {
+ continue;
+ }
+ // remove leading javadoc *
+ if (line.startsWith("*")) {
+ line = line.substring(1);
+ line = line.trim();
+ }
+
// terminate if we reach @param, @return or @deprecated as we only want the javadoc summary
if (line.startsWith("@param") || line.startsWith("@return") || line.startsWith("@deprecated")) {
break;
@@ -277,7 +286,8 @@ public final class JsonSchemaHelper {
line = line.replaceAll("<.*?>", "");
// remove all inlined javadoc links, eg such as {@link org.apache.camel.spi.Registry}
- line = line.replaceAll("\\{\\@\\w+\\s([\\w.]+)\\}", "$1");
+ // use #? to remove leading # in case its a local reference
+ line = line.replaceAll("\\{\\@\\w+\\s#?([\\w.#(\\d,)]+)\\}", "$1");
// we are starting from a new line, so add a whitespace
if (!first) {
diff --git a/tooling/apt/src/test/java/org/apache/camel/tools/apt/JsonSchemaHelperTest.java b/tooling/apt/src/test/java/org/apache/camel/tools/apt/JsonSchemaHelperTest.java
new file mode 100644
index 0000000..718b799
--- /dev/null
+++ b/tooling/apt/src/test/java/org/apache/camel/tools/apt/JsonSchemaHelperTest.java
@@ -0,0 +1,84 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.camel.tools.apt;
+
+import org.apache.camel.tools.apt.helper.JsonSchemaHelper;
+import org.junit.Assert;
+import org.junit.Test;
+
+public class JsonSchemaHelperTest {
+
+ private static final String JAVADOC = ""
+ + " * When in streaming mode, then the splitter splits the original message on-demand, and each splitted\n"
+ + " * message is processed one by one. This reduces memory usage as the splitter do not split all the messages first,\n"
+ + " * but then we do not know the total size, and therefore the {@link org.apache.camel.Exchange#SPLIT_SIZE} is empty.\n"
+ + " * <p/>\n"
+ + " * In non-streaming mode (default) the splitter will split each message first, to know the total size, and then\n"
+ + " * process each message one by one. This requires to keep all the splitted messages in memory and therefore requires\n"
+ + " * more memory. The total size is provided in the {@link org.apache.camel.Exchange#SPLIT_SIZE} header.\n"
+ + " * <p/>\n"
+ + " * The streaming mode also affects the aggregation behavior.\n"
+ + " * If enabled then Camel will process replies out-of-order, eg in the order they come back.\n"
+ + " * If disabled, Camel will process replies in the same order as the messages was splitted.\n"
+ + " *\n"
+ + " * @return the builder\n"
+ + " */\n";
+
+ private static final String EXPECTED_OUT = "When in streaming mode, then the splitter splits the original message on-demand, and each splitted message is processed one by one."
+ + " This reduces memory usage as the splitter do not split all the messages first, but then we do not know the total size, and therefore"
+ + " the org.apache.camel.Exchange#SPLIT_SIZE is empty. In non-streaming mode (default) the splitter will split each message first, to know"
+ + " the total size, and then process each message one by one. This requires to keep all the splitted messages in memory and therefore requires"
+ + " more memory. The total size is provided in the org.apache.camel.Exchange#SPLIT_SIZE header. The streaming mode also affects the aggregation"
+ + " behavior. If enabled then Camel will process replies out-of-order, eg in the order they come back. If disabled, Camel will process replies"
+ + " in the same order as the messages was splitted.";
+
+ private static final String JAVADOC2 = ""
+ + " **\n"
+ + " * Sets a grace period after which the mock endpoint will re-assert\n"
+ + " * to ensure the preliminary assertion is still valid.\n"
+ + " * <p/>\n"
+ + " * This is used for example to assert that <b>exactly</b> a number of messages \n"
+ + " * arrives. For example if {@link #expectedMessageCount(int)} was set to 5, then\n"
+ + " * the assertion is satisfied when 5 or more message arrives. To ensure that\n"
+ + " * exactly 5 messages arrives, then you would need to wait a little period\n"
+ + " * to ensure no further message arrives. This is what you can use this\n"
+ + " * {@link #setAssertPeriod(long)} method for.\n"
+ + " * <p/>\n"
+ + " * By default this period is disabled.\n"
+ + " *\n"
+ + " * @param period grace period in millis\n"
+ + " *\n";
+
+ private static final String EXPECTED_OUT2 = "Sets a grace period after which the mock endpoint will re-assert to ensure the preliminary assertion "
+ + "is still valid. This is used for example to assert that exactly a number of messages arrives. For example if expectedMessageCount(int)"
+ + " was set to 5, then the assertion is satisfied when 5 or more message arrives. To ensure that exactly 5 messages arrives, then you would need"
+ + " to wait a little period to ensure no further message arrives. This is what you can use this setAssertPeriod(long) method for. By default"
+ + " this period is disabled.";
+
+ @Test
+ public void testSanitizeJavaDoc() throws Exception {
+ String s = "* more memory. The total size is provided in the {@link org.apache.camel.Exchange#SPLIT_SIZE} header.";
+ String s2 = JsonSchemaHelper.sanitizeDescription(s, false);
+ Assert.assertEquals("more memory. The total size is provided in the org.apache.camel.Exchange#SPLIT_SIZE header.", s2);
+
+ String out = JsonSchemaHelper.sanitizeDescription(JAVADOC, false);
+ Assert.assertEquals(EXPECTED_OUT, out);
+
+ String out2 = JsonSchemaHelper.sanitizeDescription(JAVADOC2, false);
+ Assert.assertEquals(EXPECTED_OUT2, out2);
+ }
+}