From: Robert Varga <robert.varga@pantheon.tech>
Date: Mon, 12 Jul 2021 09:15:54 +0000 (+0200)
Subject: Fix javadoc compatibility
X-Git-Tag: v9.0.2~24
X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?p=mdsal.git;a=commitdiff_plain;h=a097ce084ca81e5b2f2ccbf15cf37e29511083f5

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 18ff084c69..564a80a01a 100644
--- 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 bdc3c88c4a..89be6fbb6e 100644
--- 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 09e808d47c..ea75978fc3 100644
--- 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 7a5338d128..5feed76f00 100644
--- 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 fb11711c03..9c06d7d589 100644
--- 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.
      *