From fc1245e6126dc7c3e31ee0a33440dcd047c6cd3f Mon Sep 17 00:00:00 2001
From: Robert Varga <robert.varga@pantheon.tech>
Date: Fri, 17 Feb 2023 21:13:24 +0100
Subject: [PATCH] Improve TreeNode and Version documentation

These two constructs are tighly related to well-known MVCC mechanics.
Update their documentation to provide links to Wikipedia explaining
their function.

Change-Id: I112c23cdcaa3aa07f93e78f86d5eb188e21cf73e
Signed-off-by: Robert Varga <robert.varga@pantheon.tech>
---
 .../yang/data/tree/impl/node/TreeNode.java    |  7 +++++--
 .../yang/data/tree/impl/node/Version.java     | 19 ++++++++++++++-----
 2 files changed, 19 insertions(+), 7 deletions(-)

diff --git a/data/yang-data-tree-ri/src/main/java/org/opendaylight/yangtools/yang/data/tree/impl/node/TreeNode.java b/data/yang-data-tree-ri/src/main/java/org/opendaylight/yangtools/yang/data/tree/impl/node/TreeNode.java
index 21e122f0c3..50ad005b0a 100644
--- a/data/yang-data-tree-ri/src/main/java/org/opendaylight/yangtools/yang/data/tree/impl/node/TreeNode.java
+++ b/data/yang-data-tree-ri/src/main/java/org/opendaylight/yangtools/yang/data/tree/impl/node/TreeNode.java
@@ -20,8 +20,11 @@ import org.opendaylight.yangtools.yang.data.api.schema.OrderedNodeContainer;
 import org.opendaylight.yangtools.yang.data.api.schema.tree.StoreTreeNode;
 
 /**
- * A very basic data tree node. It has a version (when it was last modified), a subtree version (when any of its
- * children were modified) and some read-only data.
+ * A very basic data tree node. It has a {@link #getVersion()} (when it was last modified),
+ * a {@link #getSubtreeVersion()} (when any of its children were modified) and some read-only data. In terms of
+ * <a href="https://en.wikipedia.org/wiki/Multiversion_concurrency_control#Implementation">MVCC</a>, the former
+ * corresponds to the this node's current Read Timestamp (RTS(P), where P is this node). The latter is the most recent
+ * Read Timestamp in this node's accessible children.
  *
  * <p>
  * Semantic difference between these two is important when dealing with modifications involving parent/child
diff --git a/data/yang-data-tree-ri/src/main/java/org/opendaylight/yangtools/yang/data/tree/impl/node/Version.java b/data/yang-data-tree-ri/src/main/java/org/opendaylight/yangtools/yang/data/tree/impl/node/Version.java
index 4abfd75bce..cd5257781b 100644
--- a/data/yang-data-tree-ri/src/main/java/org/opendaylight/yangtools/yang/data/tree/impl/node/Version.java
+++ b/data/yang-data-tree-ri/src/main/java/org/opendaylight/yangtools/yang/data/tree/impl/node/Version.java
@@ -7,14 +7,23 @@
  */
 package org.opendaylight.yangtools.yang.data.tree.impl.node;
 
+import org.opendaylight.yangtools.concepts.Immutable;
+
 /**
- * The concept of a version, either node version, or a subtree version. The
- * only interface contract this class has is that no two versions are the
- * same.
+ * The concept of a version, either node version, or a subtree version. The only interface contract this class has is
+ * that no two {@link Version} are the same.
+ *
+ * <p>
+ * This class relies on Java Virtual machine's guarantee that the identity of an Object is distinct from any other
+ * Object in the Java heap.
+ *
+ * <p>
+ * From data management perspective, this concept serves as JVM-level MVCC
+ * <a href="https://en.wikipedia.org/wiki/Multiversion_concurrency_control#Implementation">timestamp (TS)</a>.
  */
-public final class Version {
+public final class Version implements Immutable {
     private Version() {
-
+        // Hidden on purpose
     }
 
     /**
-- 
2.36.6