From 29dd9d03f8b4100ce0525b1b93517a50d95db0d9 Mon Sep 17 00:00:00 2001
From: Robert Varga <robert.varga@pantheon.tech>
Date: Fri, 23 Oct 2020 23:58:58 +0200
Subject: [PATCH] Fix MatchBuilderPath documentation

We have a sentence trailing off, fix it up. Since we are introducing
a new pointer, update LambdaDecoder documentation. QueryExpression
gets a free pass on whitespace.

Change-Id: Ib5f66a80b99f5be18b5b9f41be4fd850435465f8
Signed-off-by: Robert Varga <robert.varga@pantheon.tech>
---
 .../mdsal/binding/api/query/MatchBuilderPath.java        | 6 ++++--
 .../mdsal/binding/api/query/QueryExpression.java         | 2 --
 .../mdsal/binding/dom/adapter/query/LambdaDecoder.java   | 9 +++++++--
 3 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/query/MatchBuilderPath.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/query/MatchBuilderPath.java
index 66c2f5ac66..e753d58bc9 100644
--- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/query/MatchBuilderPath.java
+++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/query/MatchBuilderPath.java
@@ -169,12 +169,14 @@ public interface MatchBuilderPath<O extends DataObject, T extends DataObject> ex
     @FunctionalInterface
     public interface LeafReference<P, C> extends Serializable {
         /**
-         * Dummy method to express the method signature of a typical getter. This method
+         * Dummy method to express the method signature of a typical getter. Due to this match we can match any Java
+         * method reference which takes in {@code parent} and results in {@code child} -- expose the feature of using
+         * {@code Parent::getChild} method shorthand.
          *
          * @param parent Parent object
          * @return Leaf value
          * @deprecated This method is present only for technical realization of taking the method reference and should
-         *             never be involved directly.
+         *             never be involved directly. See {@code LambdaDecoder} for gory details.
          */
         @Deprecated(forRemoval = true)
         C dummyMethod(P parent);
diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/query/QueryExpression.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/query/QueryExpression.java
index a9c68349f3..84aec89827 100644
--- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/query/QueryExpression.java
+++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/query/QueryExpression.java
@@ -80,8 +80,6 @@ import org.opendaylight.yangtools.yang.binding.DataObject;
  * The distinction here is made by selecting different root paths: the first will specify the entire {@code foo} list,
  * while the second will select a specific {@code foo} entry.
  *
- *
- *
  * @param <T> Result object type
  */
 @Beta
diff --git a/binding/mdsal-binding-dom-adapter/src/main/java/org/opendaylight/mdsal/binding/dom/adapter/query/LambdaDecoder.java b/binding/mdsal-binding-dom-adapter/src/main/java/org/opendaylight/mdsal/binding/dom/adapter/query/LambdaDecoder.java
index 55edf22515..d5d5cd43da 100644
--- a/binding/mdsal-binding-dom-adapter/src/main/java/org/opendaylight/mdsal/binding/dom/adapter/query/LambdaDecoder.java
+++ b/binding/mdsal-binding-dom-adapter/src/main/java/org/opendaylight/mdsal/binding/dom/adapter/query/LambdaDecoder.java
@@ -14,11 +14,13 @@ import com.google.common.base.MoreObjects;
 import com.google.common.cache.CacheBuilder;
 import com.google.common.cache.CacheLoader;
 import com.google.common.cache.LoadingCache;
+import java.io.Serializable;
 import java.lang.invoke.SerializedLambda;
 import java.lang.reflect.Method;
 import java.security.AccessController;
 import java.security.PrivilegedActionException;
 import java.security.PrivilegedExceptionAction;
+import java.util.function.Function;
 import org.opendaylight.mdsal.binding.api.query.MatchBuilderPath.LeafReference;
 import org.opendaylight.yangtools.concepts.Immutable;
 
@@ -28,8 +30,8 @@ import org.opendaylight.yangtools.concepts.Immutable;
  * to {@link LeafReference} lambdas.
  *
  * <p>
- * We then assume runtime is following guidance around {@link SerializedLambda}, thus Serializable lambdas have a
- * {@code writeReplace()} method and that it produces {@link SerializedLambda} -- which we use to get the information
+ * We then assume runtime is following guidance around {@link SerializedLambda}, thus {@link Serializable} lambdas have
+ * a {@code writeReplace()} method and it produces a {@link SerializedLambda} -- which we use to get the information
  * about what the lambda does at least in the single case we support.
  *
  * <p>
@@ -43,8 +45,11 @@ import org.opendaylight.yangtools.concepts.Immutable;
  *   <li>it creates additional implementation of the interface, bringing the system-wide total to 3, which can hurt
  *       JIT's decisions</li>
  * </ul>
+ * While that approach would certainly be feasible and would on top of plain {@link Function}, overall it would be
+ * messier, less type-safe and a perf-killer.
  */
 final class LambdaDecoder {
+    // FIXME: when we have JDK16: this should be a record
     static final class LambdaTarget implements Immutable {
         final String targetClass;
         final String targetMethod;
-- 
2.36.6