From 331797328ab14acaa39efa7fdfb0e571860baca9 Mon Sep 17 00:00:00 2001
From: Robert Varga <robert.varga@pantheon.tech>
Date: Fri, 25 May 2018 13:47:10 +0200
Subject: [PATCH] Improve InstanceIdentifier documentation

This adds a few javadocs to clarify what is going on.

Change-Id: I9983e7d6715fc06c7d18a61fd74a0660c8d2b4ce
Signed-off-by: Robert Varga <robert.varga@pantheon.tech>
---
 .../yang/binding/InstanceIdentifier.java      | 76 ++++++++++++++-----
 1 file changed, 59 insertions(+), 17 deletions(-)

diff --git a/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/InstanceIdentifier.java b/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/InstanceIdentifier.java
index 5dfbfb8513..11b77cc5a0 100644
--- a/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/InstanceIdentifier.java
+++ b/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/InstanceIdentifier.java
@@ -343,15 +343,45 @@ public class InstanceIdentifier<T extends DataObject> implements Path<InstanceId
             HashCodeBuilder.nextHashCode(hash, arg), isWildcarded());
     }
 
+    /**
+     * Create an InstanceIdentifier for a child container. This method is a more efficient equivalent to
+     * {@code builder().child(container).build()}.
+     *
+     * @param container Container to append
+     * @param <N> Container type
+     * @return An InstanceIdentifier.
+     * @throws NullPointerException if {@code container} is null
+     */
     public final <N extends ChildOf<? super T>> InstanceIdentifier<N> child(final Class<N> container) {
         return childIdentifier(new Item<>(container));
     }
 
+    /**
+     * Create an InstanceIdentifier for a child list item. This method is a more efficient equivalent to
+     * {@code builder().child(listItem, listKey).build()}.
+     *
+     * @param listItem List to append
+     * @param listKey List key
+     * @param <N> List type
+     * @param <K> Key type
+     * @return An InstanceIdentifier.
+     * @throws NullPointerException if any argument is null
+     */
+    @SuppressWarnings("unchecked")
     public final <N extends Identifiable<K> & ChildOf<? super T>, K extends Identifier<N>> KeyedInstanceIdentifier<N, K>
             child(final Class<N> listItem, final K listKey) {
         return (KeyedInstanceIdentifier<N, K>) childIdentifier(new IdentifiableItem<>(listItem, listKey));
     }
 
+    /**
+     * Create an InstanceIdentifier for a child augmentation. This method is a more efficient equivalent to
+     * {@code builder().augmentation(container).build()}.
+     *
+     * @param container Container to append
+     * @param <N> Container type
+     * @return An InstanceIdentifier.
+     * @throws NullPointerException if {@code container} is null
+     */
     public final <N extends DataObject & Augmentation<? super T>> InstanceIdentifier<N> augmentation(
             final Class<N> container) {
         return childIdentifier(new Item<>(container));
@@ -398,7 +428,8 @@ public class InstanceIdentifier<T extends DataObject> implements Path<InstanceId
      *
      * @param container Base container
      * @param <T> Type of the container
-     * @return New IsntanceIdentifierBuilder
+     * @return A new {@link InstanceIdentifierBuilder}
+     * @throws NullPointerException if {@code container} is null
      */
     public static <T extends ChildOf<? extends DataRoot>> InstanceIdentifierBuilder<T> builder(
             final Class<T> container) {
@@ -414,6 +445,7 @@ public class InstanceIdentifier<T extends DataObject> implements Path<InstanceId
      * @param <N> List type
      * @param <K> List key
      * @return A new {@link InstanceIdentifierBuilder}
+     * @throws NullPointerException if any argument is null
      */
     public static <N extends Identifiable<K> & ChildOf<? extends DataRoot>,
             K extends Identifier<N>> InstanceIdentifierBuilder<N> builder(final Class<N> listItem, final K listKey) {
@@ -427,6 +459,7 @@ public class InstanceIdentifier<T extends DataObject> implements Path<InstanceId
      * @param pathArguments The path to a specific node in the data tree
      * @return InstanceIdentifier instance
      * @throws IllegalArgumentException if pathArguments is empty or contains a null element.
+     * @throws NullPointerException if {@code pathArguments} is null
      */
     private static InstanceIdentifier<?> internalCreate(final Iterable<PathArgument> pathArguments) {
         final Iterator<? extends PathArgument> it = requireNonNull(pathArguments, "pathArguments may not be null")
@@ -471,9 +504,9 @@ public class InstanceIdentifier<T extends DataObject> implements Path<InstanceId
             @SuppressWarnings("unchecked")
             final Iterable<PathArgument> immutableArguments = (Iterable<PathArgument>) pathArguments;
             return internalCreate(immutableArguments);
-        } else {
-            return internalCreate(ImmutableList.copyOf(pathArguments));
         }
+
+        return internalCreate(ImmutableList.copyOf(pathArguments));
     }
 
     /**
@@ -534,6 +567,11 @@ public class InstanceIdentifier<T extends DataObject> implements Path<InstanceId
      * path in overall data tree.
      */
     public interface PathArgument extends Comparable<PathArgument> {
+        /**
+         * Return the data object type backing this PathArgument.
+         *
+         * @return Data object type.
+         */
         Class<? extends DataObject> getType();
     }
 
@@ -612,6 +650,11 @@ public class InstanceIdentifier<T extends DataObject> implements Path<InstanceId
             this.key = requireNonNull(key, "Key may not be null.");
         }
 
+        /**
+         * Return the data object type backing this PathArgument.
+         *
+         * @return Data object type.
+         */
         public T getKey() {
             return this.key;
         }
@@ -632,7 +675,6 @@ public class InstanceIdentifier<T extends DataObject> implements Path<InstanceId
         }
     }
 
-
     public interface InstanceIdentifierBuilder<T extends DataObject> extends Builder<InstanceIdentifier<T>> {
         /**
          * Append the specified container as a child of the current InstanceIdentifier referenced by the builder.
@@ -643,18 +685,17 @@ public class InstanceIdentifier<T extends DataObject> implements Path<InstanceId
          * Example,
          * <pre>
          *     InstanceIdentifier.builder().child(Nodes.class).build();
-         *
          * </pre>
          *
          * NOTE :- The above example is only for illustration purposes InstanceIdentifier.builder() has been deprecated
          * and should not be used. Use InstanceIdentifier.builder(Nodes.class) instead
          *
-         * @param container
-         * @param <N>
-         * @return
+         * @param container Container to append
+         * @param <N> Container type
+         * @return this builder
+         * @throws NullPointerException if {@code container} is null
          */
-        <N extends ChildOf<? super T>> InstanceIdentifierBuilder<N> child(
-                Class<N> container);
+        <N extends ChildOf<? super T>> InstanceIdentifierBuilder<N> child(Class<N> container);
 
         /**
          * Append the specified listItem as a child of the current InstanceIdentifier referenced by the builder.
@@ -662,11 +703,12 @@ public class InstanceIdentifier<T extends DataObject> implements Path<InstanceId
          * This method should be used when you want to build an instance identifier by appending a specific list element
          * to the identifier
          *
-         * @param listItem
-         * @param listKey
-         * @param <N>
-         * @param <K>
-         * @return
+         * @param listItem List to append
+         * @param listKey List key
+         * @param <N> List type
+         * @param <K> Key type
+         * @return this builder
+         * @throws NullPointerException if any argument is null
          */
         <N extends Identifiable<K> & ChildOf<? super T>, K extends Identifier<N>> InstanceIdentifierBuilder<N> child(
                 Class<N> listItem, K listKey);
@@ -678,9 +720,9 @@ public class InstanceIdentifier<T extends DataObject> implements Path<InstanceId
          * @param container augmentation class
          * @param <N> augmentation type
          * @return this builder
+         * @throws NullPointerException if {@code container} is null
          */
-        <N extends DataObject & Augmentation<? super T>> InstanceIdentifierBuilder<N> augmentation(
-                Class<N> container);
+        <N extends DataObject & Augmentation<? super T>> InstanceIdentifierBuilder<N> augmentation(Class<N> container);
 
         /**
          * Build the instance identifier.
-- 
2.36.6