From 94d4f50d34d5b7c690d7fa92b33e7db7965f455c Mon Sep 17 00:00:00 2001
From: Robert Varga <robert.varga@pantheon.tech>
Date: Thu, 18 Jan 2024 19:52:54 +0100
Subject: [PATCH] Clean up documentation

We are about to duplicate a number of methods, clean up their
documentation, so we do not accumulate work.

Change-Id: I119b4009ebef1fe8af4a7cc8057ee86bdf2e1621
JIRA: MDSAL-819
Signed-off-by: Robert Varga <robert.varga@pantheon.tech>
---
 .../binding/api/DataTreeChangeService.java    | 75 +++++++++----------
 .../dom/api/DOMDataTreeChangeService.java     |  2 +-
 2 files changed, 35 insertions(+), 42 deletions(-)

diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeChangeService.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeChangeService.java
index 36846695ba..8ab7aa61ab 100644
--- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeChangeService.java
+++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeChangeService.java
@@ -36,9 +36,9 @@ public interface DataTreeChangeService extends BindingService {
      * {@link Registration#close()} method on the returned object.
      *
      * <p>
-     * You MUST explicitly unregister your listener when you no longer want to receive
-     * notifications. This is especially true in OSGi environments, where failure to
-     * do so during bundle shutdown can lead to stale listeners being still registered.
+     * You <b>MUST</b> explicitly unregister your listener when you no longer want to receive notifications. This is
+     * especially true in OSGi environments, where failure to do so during bundle shutdown can lead to stale listeners
+     * being still registered.
      *
      * @param treeId Data tree identifier of the subtree which should be watched for changes
      * @param listener Listener instance which is being registered
@@ -49,32 +49,30 @@ public interface DataTreeChangeService extends BindingService {
         @NonNull DataTreeChangeListener<T> listener);
 
     /**
-     * Registers a {@link DataTreeChangeListener} to receive
-     * notifications when data changes under a given path in the conceptual data tree.
+     * Registers a {@link DataTreeChangeListener} to receive notifications when data changes under a given path in the
+     * conceptual data tree.
      *
      * <p>
-     * You are able to register for notifications  for any node or subtree
-     * which can be represented using {@link DataTreeIdentifier}.
+     * You are able to register for notifications  for any node or subtree which can be represented using
+     * {@link DataTreeIdentifier}.
      *
      * <p>
-     * This method returns a {@link Registration} object. To
-     * "unregister" your listener for changes call the {@link Registration#close()}
-     * method on the returned object.
+     * This method returns a {@link Registration} object. To "unregister" your listener for changes call the
+     * {@link Registration#close()} method on the returned object.
      *
      * <p>
-     * You MUST explicitly unregister your listener when you no longer want to receive
-     * notifications. This is especially true in OSGi environments, where failure to
-     * do so during bundle shutdown can lead to stale listeners being still registered.
-     * @implSpec This method provides {@link DataListenerAdapter} as listener during
-     *      the registration of {@link DataTreeChangeListener}. This would allow users
-     *      to know the last state of data instead of getting details about what changed
-     *      in the entire tree.
-     * @param treeId Data tree identifier of the subtree which should be watched for
-     *            changes.
+     * You <b>MUST</b> explicitly unregister your listener when you no longer want to receive notifications. This is
+     * especially true in OSGi environments, where failure to do so during bundle shutdown can lead to stale listeners
+     * being still registered.
+     *
+     * @implSpec This method provides {@link DataListenerAdapter} as listener during the registration of
+     *           {@link DataTreeChangeListener}. This would allow users to know the last state of data instead of
+     *           getting details about what changed in the entire tree.
+     *
+     * @param treeId Data tree identifier of the subtree which should be watched for changes.
      * @param listener Listener instance which is being registered
-     * @return Listener registration object, which may be used to unregister
-     *         your listener using {@link Registration#close()} to stop
-     *         delivery of change events.
+     * @return Listener registration object, which may be used to unregister your listener using
+     *         {@link Registration#close()} to stop delivery of change events.
      */
     default <T extends DataObject> @NonNull Registration registerDataListener(
             final @NonNull DataTreeIdentifier<T> treeId, final @NonNull DataListener<T> listener) {
@@ -82,34 +80,29 @@ public interface DataTreeChangeService extends BindingService {
     }
 
     /**
-     * Registers a {@link DataTreeChangeListener} to receive
-     * notifications about the last data state when it changes under a given path in the conceptual data
-     * tree.
+     * Registers a {@link DataTreeChangeListener} to receive notifications about the last data state when it changes
+     * under a given path in the conceptual data tree.
      *
      * <p>
-     * You are able to register for notifications  for any node or subtree
-     * which can be represented using {@link DataTreeIdentifier}.
+     * You are able to register for notifications  for any node or subtree which can be represented using
+     * {@link DataTreeIdentifier}.
      *
      * <p>
-     * This method returns a {@link Registration} object. To
-     * "unregister" your listener for changes call the {@link Registration#close()}
-     * method on the returned object.
+     * This method returns a {@link Registration} object. To "unregister" your listener for changes call the
+     * {@link Registration#close()} method on the returned object.
      *
      * <p>
-     * You MUST explicitly unregister your listener when you no longer want to receive
-     * notifications. This is especially true in OSGi environments, where failure to
-     * do so during bundle shutdown can lead to stale listeners being still registered.
+     * You <b>MUST</b> explicitly unregister your listener when you no longer want to receive notifications. This is
+     * especially true in OSGi environments, where failure to do so during bundle shutdown can lead to stale listeners
+     * being still registered.
      *
-     * @implSpec This method provides {@link DataChangeListenerAdapter} as listener during
-     *      the registration of {@link DataTreeChangeListener}, which provides a comparison
-     *      of before-value and after-value.
+     * @implSpec This method provides {@link DataChangeListenerAdapter} as listener during the registration of
+     *           {@link DataTreeChangeListener}, which provides a comparison of before-value and after-value.
      *
-     * @param treeId Data tree identifier of the subtree which should be watched for
-     *            changes.
+     * @param treeId Data tree identifier of the subtree which should be watched for changes.
      * @param listener Listener instance which is being registered
-     * @return Listener registration object, which may be used to unregister
-     *         your listener using {@link Registration#close()} to stop
-     *         delivery of change events.
+     * @return Listener registration object, which may be used to unregister your listener using
+     *         {@link Registration#close()} to stop  delivery of change events.
      */
     default <T extends DataObject> @NonNull Registration registerDataChangeListener(
             final @NonNull DataTreeIdentifier<T> treeId, final @NonNull DataChangeListener<T> listener) {
diff --git a/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMDataTreeChangeService.java b/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMDataTreeChangeService.java
index 127c2653c2..8585feae4e 100644
--- a/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMDataTreeChangeService.java
+++ b/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMDataTreeChangeService.java
@@ -44,7 +44,7 @@ public interface DOMDataTreeChangeService extends DOMDataBroker.Extension {
      * @param listener Listener instance which is being registered
      * @return A {@link Registration} object, which may be used to unregister your listener using
      *         {@link Registration#close()} to stop delivery of change events.
-     * @throws NullPointerException if any of the arguments is null
+     * @throws NullPointerException if any of the arguments is {@code null}
      */
     Registration registerDataTreeChangeListener(DOMDataTreeIdentifier treeId, DOMDataTreeChangeListener listener);
 }
-- 
2.36.6