Fix javadoc compatibility

JDK13+ is much stricter about what is considered valid Javadoc. Fixup
to make compilation pass on JDK17. This breaks linting on JDK11, hence
we also disable it for now.

Change-Id: I4ee650e13a135349c9522ad74fe098f088c09e5d
Signed-off-by: Robert Varga <robert.varga@pantheon.tech>

diff --git a/binding/mdsal-binding-api/pom.xml b/binding/mdsal-binding-api/pom.xml
index 18ff084c69c86d48ef8549427ea02df325989d50..564a80a01a8cb655323540631019cdf89ec95478 100644 (file)
--- a/binding/mdsal-binding-api/pom.xml
+++ b/binding/mdsal-binding-api/pom.xml
@@ -56,6 +56,18 @@
         </dependency>
     </dependencies>
 
+    <!-- FIXME: remove this section once we require JDK17+ -->
+    <build>
+        <plugins>
+            <plugin>
+                <artifactId>maven-javadoc-plugin</artifactId>
+                <configuration combine.children="append">
+                    <doclint>-html</doclint>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+
     <scm>
         <connection>scm:git:http://git.opendaylight.org/gerrit/controller.git</connection>
         <developerConnection>scm:git:ssh://git.opendaylight.org:29418/controller.git</developerConnection>

diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/WriteTransaction.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/WriteTransaction.java
index bdc3c88c4ad5d56b5cc464b8a74f85cc81b25950..89be6fbb6e3f2622c16f2894077fbe11443122e7 100644 (file)
--- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/WriteTransaction.java
+++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/WriteTransaction.java
@@ -113,7 +113,7 @@ public interface WriteTransaction extends Transaction, WriteOperations {
      * The effects of a successful commit of data depends on listeners and commit participants that are registered with
      * the data broker.
      *
-     * <h3>Example usage:</h3>
+     * <h4>Example usage:</h4>
      * <pre>
      *  private void doWrite(final int tries) {
      *      WriteTransaction writeTx = dataBroker.newWriteOnlyTransaction();
@@ -141,7 +141,7 @@ public interface WriteTransaction extends Transaction, WriteOperations {
      * doWrite(2);
      * </pre>
      *
-     * <h2>Failure scenarios</h2>
+     * <h4>Failure scenarios</h4>
      *
      * <p>
      * Transaction may fail because of multiple reasons, such as
@@ -164,7 +164,7 @@ public interface WriteTransaction extends Transaction, WriteOperations {
      *   </li>
      * </ul>
      *
-     * <h3>Change compatibility</h3>
+     * <h4>Change compatibility</h4>
      * There are several sets of changes which could be considered incompatible between two transactions which are
      * derived from same initial state. Rules for conflict detection applies recursively for each subtree level.
      *
@@ -411,9 +411,9 @@ public interface WriteTransaction extends Transaction, WriteOperations {
      * </table>
      *
      *
-     * <h3>Examples of failure scenarios</h3>
+     * <h4>Examples of failure scenarios</h4>
      *
-     * <h4>Conflict of two transactions</h4>
+     * <h5>Conflict of two transactions</h5>
      * This example illustrates two concurrent transactions, which derived from same initial state
      * of data tree and proposes conflicting modifications.
      *

diff --git a/docs/pom.xml b/docs/pom.xml
index 09e808d47c4cefc20c703a73db3de09317bd6990..ea75978fc31c93b0b028129647e647148e3ba21a 100644 (file)
--- a/docs/pom.xml
+++ b/docs/pom.xml
@@ -603,6 +603,9 @@
                 </executions>
                 <!-- FIXME: remove this section once we can activate javadoc-links profile -->
                 <configuration combine.children="append">
+                    <!-- byte-buddy's sources fail with JDK17 -->
+                    <doclint>-html</doclint>
+
                     <links>
                         <link>https://junit.org/junit4/javadoc/4.13/</link>
                         <link>http://hamcrest.org/JavaHamcrest/javadoc/2.2/</link>

diff --git a/dom/mdsal-dom-api/pom.xml b/dom/mdsal-dom-api/pom.xml
index 7a5338d128782cd09f7e5f081ec41f66a352e2d3..5feed76f00f988bee5dc5af1afaf9e39354085a8 100644 (file)
--- a/dom/mdsal-dom-api/pom.xml
+++ b/dom/mdsal-dom-api/pom.xml
@@ -53,6 +53,18 @@
         </dependency>
     </dependencies>
 
+    <!-- FIXME: remove this section once we require JDK17+ -->
+    <build>
+        <plugins>
+            <plugin>
+                <artifactId>maven-javadoc-plugin</artifactId>
+                <configuration combine.children="append">
+                    <doclint>-html</doclint>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+
     <scm>
         <connection>scm:git:http://git.opendaylight.org/gerrit/controller.git</connection>
         <developerConnection>scm:git:ssh://git.opendaylight.org:29418/controller.git</developerConnection>

diff --git a/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMDataTreeWriteTransaction.java b/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMDataTreeWriteTransaction.java
index fb11711c03ea6cbe455b62c3d46b1bc97e01e89f..9c06d7d589a1f2e23ba73bcb0c9e4a5383c3ab64 100644 (file)
--- a/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMDataTreeWriteTransaction.java
+++ b/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMDataTreeWriteTransaction.java
@@ -107,7 +107,7 @@ public interface DOMDataTreeWriteTransaction extends DOMDataTreeTransaction, DOM
      * The effects of a successful commit of data depends on listeners and commit participants that are registered with
      * the data broker.
      *
-     * <h3>Example usage:</h3>
+     * <h4>Example usage:</h4>
      * <pre>
      *  private void doWrite(final int tries) {
      *      WriteTransaction writeTx = dataBroker.newWriteOnlyTransaction();
@@ -135,7 +135,7 @@ public interface DOMDataTreeWriteTransaction extends DOMDataTreeTransaction, DOM
      * doWrite(2);
      * </pre>
      *
-     * <h2>Failure scenarios</h2>
+     * <h4>Failure scenarios</h4>
      *
      * <p>
      * Transaction may fail because of multiple reasons, such as
@@ -158,7 +158,7 @@ public interface DOMDataTreeWriteTransaction extends DOMDataTreeTransaction, DOM
      *   </li>
      * </ul>
      *
-     * <h3>Change compatibility</h3>
+     * <h4>Change compatibility</h4>
      * There are several sets of changes which could be considered incompatible between two transactions which are
      * derived from same initial state. Rules for conflict detection applies recursively for each subtree level.
      *
@@ -405,9 +405,9 @@ public interface DOMDataTreeWriteTransaction extends DOMDataTreeTransaction, DOM
      * </table>
      *
      *
-     * <h3>Examples of failure scenarios</h3>
+     * <h4>Examples of failure scenarios</h4>
      *
-     * <h4>Conflict of two transactions</h4>
+     * <h5>Conflict of two transactions</h5>
      * This example illustrates two concurrent transactions, which derived from same initial state
      * of data tree and proposes conflicting modifications.
      *