From 3c45e3dec46d38b7c6fe121ca23d48ac602fe55f Mon Sep 17 00:00:00 2001
From: Robert Varga <robert.varga@pantheon.tech>
Date: Wed, 10 Apr 2019 13:10:57 +0200
Subject: [PATCH] Document BindingCodec/Serializer/Deserializer

These interfaces are not documented at all, owing partly to the fact
they are are implementation of mdsal-binding-dom-codec, whose design
currently requires placing codecs into the same class loader as
generated code -- hence they leak to the common binding support
package.

Change-Id: Ib576b9aeddcc644d5b1f44a2047e775cc5266245
JIRA: MDSAL-401
Signed-off-by: Robert Varga <robert.varga@pantheon.tech>
---
 .../opendaylight/yangtools/yang/binding/BindingCodec.java  | 5 +++++
 .../yangtools/yang/binding/BindingDeserializer.java        | 7 ++++++-
 .../yangtools/yang/binding/BindingSerializer.java          | 7 ++++++-
 3 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/BindingCodec.java b/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/BindingCodec.java
index a812126336..e8c9a107d1 100644
--- a/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/BindingCodec.java
+++ b/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/BindingCodec.java
@@ -9,6 +9,11 @@ package org.opendaylight.yangtools.yang.binding;
 
 import org.opendaylight.yangtools.concepts.Codec;
 
+/**
+ * Combination of {@link BindingSerializer} and {@link BindingDeserializer}. This interface is present in this package
+ * only due to constraints imposed by current implementation.
+ */
+// FIXME: MDSAL-401: deprecate this interface once we no longer to have in a public place
 public interface BindingCodec<P, I> extends BindingSerializer<P, I>, BindingDeserializer<I, P>, Codec<P, I> {
 
     @Override
diff --git a/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/BindingDeserializer.java b/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/BindingDeserializer.java
index dea3d992db..aa4f05e25f 100644
--- a/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/BindingDeserializer.java
+++ b/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/BindingDeserializer.java
@@ -7,7 +7,12 @@
  */
 package org.opendaylight.yangtools.yang.binding;
 
-public interface BindingDeserializer<P,I> {
+/**
+ * A serializer capable of encoding an input into some other form (typically DataObject). This interface is present in
+ * this package only due to constraints imposed by current implementation.
+ */
+// FIXME: MDSAL-401: deprecate this interface once we no longer to have in a public place
+public interface BindingDeserializer<P, I> {
 
     P deserialize(I input);
 }
diff --git a/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/BindingSerializer.java b/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/BindingSerializer.java
index fb85eae9f7..bd472e9b2b 100644
--- a/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/BindingSerializer.java
+++ b/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/BindingSerializer.java
@@ -7,6 +7,11 @@
  */
 package org.opendaylight.yangtools.yang.binding;
 
-public interface BindingSerializer<P,I> {
+/**
+ * A serializer capable of encoding an input (typically DataObject) into some other form. This interface is present in
+ * this package only due to constraints imposed by current implementation.
+ */
+// FIXME: MDSAL-401: deprecate this interface once we no longer to have in a public place
+public interface BindingSerializer<P, I> {
     P serialize(I input);
 }
-- 
2.36.6