From 951b85c68b32fa0fffa761221ed46d1efa725f48 Mon Sep 17 00:00:00 2001 From: Robert Varga Date: Thu, 15 Nov 2018 15:38:30 +0100 Subject: [PATCH] Cleanup Immutable documentation This is a simple formatting update, with small rewording to use better language. Change-Id: I51848c3a956c7251bad98418cac40ea0ffa943c2 Signed-off-by: Robert Varga (cherry picked from commit c636aeaa87c46fdea600299f193f2cbf72c3f6ca) --- .../yangtools/concepts/Immutable.java | 31 +++++++------------ 1 file changed, 12 insertions(+), 19 deletions(-) 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 fc35154808..1f17aeb6aa 100644 --- 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. * *

- * 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}. * *

- * 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. * *

- * 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. * *

- * 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 { -- 2.36.6