Document Identifiable interface contract

Somehow this core interface went undocumented, fix that and also
clarify it's companion Identifier contract.

Change-Id: I009ed90e548770b46d636e5e41c07877642682d5
Signed-off-by: Robert Varga <robert.varga@pantheon.tech>

diff --git a/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/Identifiable.java b/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/Identifiable.java
index 634373a62b75b8bde1ba53a33ecd10e1f765085b..0fe2fe48b35ea1734563ba00a003043c790a12c9 100644 (file)
--- a/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/Identifiable.java
+++ b/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/Identifiable.java
@@ -9,6 +9,15 @@ package org.opendaylight.yangtools.concepts;
 
 import org.eclipse.jdt.annotation.NonNull;
 
+/**
+ * A generalized contract of an object which has an identifier. The identifier, unlike the object carrying it, must
+ * generally comply to the interface contract outlined in {@link Identifier}, but this is not enforced in this API's
+ * design, as there are external classes, such as {@link String}, which comply to the contract without implementing it.
+ *
+ * @param <T> Identifier class, must conform to API contract outlined by {@link Identifier}, even if it does not
+ *            implement it.
+ */
+// FIXME: 3.0.0: consider requiring "T extends Serializable"
 public interface Identifiable<T> {
     /**
      * Return this objects Identifier.

diff --git a/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/Identifier.java b/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/Identifier.java
index db6216976c6f2c9d8b2e736f59d6aa6eb675e85e..06cdebc2624f3585b734f046d107bf1cb2e5d601 100644 (file)
--- a/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/Identifier.java
+++ b/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/Identifier.java
@@ -12,18 +12,19 @@ import javax.annotation.concurrent.ThreadSafe;
 
 /**
  * General identifier interface. It is primarily a marker for all things that identify concepts -- such as names,
- * addresses, classes, etc. We do not require too much, just that the identifiers are serializable (and this
+ * addresses, classes, etc. We do not require too much, just that the identifiers are serializable (and thus
  * transferable).
  *
  * <p>Implementations are expected to implement {@link #hashCode()} and {@link #equals(Object)} methods in a way,
  * which ensures that objects before and after serialization are considered equal.
  *
  * <p>Implementations are advised to use the {@link java.io.Externalizable} Proxy pattern to allow future evolution
- * of their serialization format. For further efficiency, implementation should implement {@link WritableObject},
- * so they can be efficiently embedded in other {@link Serializable} objects.
+ * of their serialization format. For further efficiency, implementations should consider implementing
+ * {@link WritableObject}, so they can be efficiently embedded in other {@link Serializable} and {@code WritableObject}s
+ * objects.
  *
  * <p>Note that this class is annotated as {@link ThreadSafe}, hence all implementations are expected to be
- * thread-safe.
+ * thread-safe. This is an implication of {@link Immutable} interface contract.
  */
 @ThreadSafe
 public interface Identifier extends Serializable, Immutable {