Cleanup Immutable documentation

This is a simple formatting update, with small rewording to use
better language.

Change-Id: I51848c3a956c7251bad98418cac40ea0ffa943c2
Signed-off-by: Robert Varga <robert.varga@pantheon.tech>
(cherry picked from commit c636aeaa87c46fdea600299f193f2cbf72c3f6ca)

diff --git a/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/Immutable.java b/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/Immutable.java
index fc35154808561ce903062a03c3e3891165c54034..1f17aeb6aa977abdf5a55e2993605073475610bf 100644 (file)
--- a/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/Immutable.java
+++ b/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/Immutable.java
@@ -8,36 +8,29 @@
 package org.opendaylight.yangtools.concepts;
 
 /**
- * Immutable Object - object does not change its state during lifecycle.
+ * Immutable Object - object does not change its externally-observable state during its lifetime.
  *
  * <p>
- * Marker interface for objects which are immutable. This interface should be
- * used directly on objects, preferably final, which are eligible for the
- * JSR-305 @Immutable annotation and objects implementing this interface are
- * required to abide to interface contract specified by @Immutable.
+ * Marker interface for objects which are immutable. This interface should be used directly on objects, preferably
+ * final, which are eligible for the JSR-305 {@code javax.annotation.concurrent.Immutable} annotation and objects
+ * implementing this interface are required to abide to interface contract specified by {@code @Immutable}.
  *
  * <p>
- * The reason for the existence of this interface is twofold: unlike @Immutable, it is
- * visible at runtime and objects can be quickly checked for compliance using a
- * quick 'instanceof' check. This is useful for code which needs to capture a
- * point-in-time snapshot of otherwise unknown objects -- a typical example
- * being logging/tracing systems. Such systems would normally have to rely on
- * serializing the object to get a stable checkpoint. Objects marked with this
- * interface are guaranteed to remain stable, thus already being a checkpoint
- * for all intents and purposes, so aside from retaining a reference no further
- * action on them is necessary.
+ * The reason for the existence of this interface is twofold: unlike {@code @Immutable}, it is visible at runtime and
+ * objects can be quickly checked for compliance using an 'instanceof' check. This is useful for code which needs to
+ * capture a point-in-time snapshot of otherwise unknown objects -- a typical example being logging/tracing systems.
+ * Such systems would normally have to rely on serializing the object to get a stable checkpoint. Objects marked with
+ * this interface are guaranteed to remain stable, thus already being a checkpoint for all intents and purposes, so
+ * aside from retaining a reference no further action on them is necessary.
  *
  * <p>
- * Implementations of this interface must not change any public state during
- * their whole lifecycle.
+ * Implementations of this interface must not change any public state during their entire lifetime.
  *
  * <p>
- * This interface is mutually exclusive with {@link Mutable} and other
- * {@link MutationBehaviour}s.
+ * This interface is mutually exclusive with {@link Mutable} and other {@link MutationBehaviour}s.
  *
  * @author Robert Varga
  * @author Tony Tkacik
- *
  */
 public interface Immutable extends MutationBehaviour<Immutable> {