Document NormalizedTree

This interface lacks javadocs, add rudimentary documentation.

JIRA: YANGTOOLS-1172
Change-Id: Ib5fec7455ab447762263d0e7069433026987e1b3
Signed-off-by: Robert Varga <robert.varga@pantheon.tech>

diff --git a/data/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/NormalizedTree.java b/data/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/NormalizedTree.java
index 6dcb60fc1505594a340da404564a61b6e6840696..8e86bf6e79ffaa66ea657b5ac974aa2b9f2ad8c6 100644 (file)
--- a/data/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/NormalizedTree.java
+++ b/data/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/NormalizedTree.java
@@ -13,14 +13,34 @@ import org.eclipse.jdt.annotation.Nullable;
 import org.opendaylight.yangtools.concepts.Immutable;
 
 /**
- * A tree of normalized {@link #data()}, with corresponding {@link #metadata()} and {@link #mountPoints()}.
+ * A tree of normalized {@link #data()}, with corresponding {@link #metadata()} and {@link #mountPoints()}. The three
+ * views are expected to be consistent in their addressing -- i.e. when traversing {@link #data()} tree,
+ * the corresponding metadata should be available through {@link NormalizedMetadata#getChildren()} and mount point
+ * attachments should be available through {@link NormalizedMountpoints#getChildren()}.
  */
+// FIXME: this interface could use a traversal utility which binds together the 'NormalizedNodeContainer' part and
+//        the corresponding metadata and/or mount points. Most notably mount points are only defined for ContainerNode
+//        and MapEntryNode.
 @Beta
 public interface NormalizedTree extends Immutable {
-
+    /**
+     * Return the data portion of this tree.
+     *
+     * @return Data portion of this tree.
+     */
     @NonNull NormalizedNode data();
 
+    /**
+     * Return the metadata portion of this tree. This portion is optional.
+     *
+     * @return Metadata portion of this tree.
+     */
     @Nullable NormalizedMetadata metadata();
 
+    /**
+     * Return the mount point portion of this tree. This portion is optional.
+     *
+     * @return mount point portion of this tree.
+     */
     @Nullable NormalizedMountpoints mountPoints();
 }