statesystem.core: Clarify querySingleState documentation

Add more details on the returned object of querySingleState.

Change-Id: I08182f6d748f1c834c13592d6eeb511e2143d09b
Signed-off-by: Francesco Robino <francesco.robino@ericsson.com>
Reviewed-on: https://git.eclipse.org/r/c/tracecompass/org.eclipse.tracecompass/+/200707
Reviewed-by: Marco Miller <marco.miller@ericsson.com>
Tested-by: Trace Compass Bot <tracecompass-bot@eclipse.org>
Tested-by: Marco Miller <marco.miller@ericsson.com>

statesystem/org.eclipse.tracecompass.statesystem.core/src/org/eclipse/tracecompass/statesystem/core/ITmfStateSystem.java

@@ -466,12 +466,18 @@ int getQuarkRelative(int startingNodeQuark, String... subPath)
      * request many entries all at the same time, you should use the
      * conventional queryFullState() + List.get() method.
      * </p>
+     * When calling this method multiple times, even if the returned
+     * {@link ITmfStateInterval} represents the same interval, there is no
+     * guarantee that the returned object is the same object.
      *
      * @param t
      *            The timestamp at which we want the state
      * @param attributeQuark
      *            Which attribute we want to get the state of
-     * @return The StateInterval representing the state
+     * @return The StateInterval representing the state. Note that the returned
+     *         object is not guaranteed to be the same object through multiple
+     *         calls, even if it represents the same interval. Only the content
+     *         is guaranteed to be the same.
      * @throws TimeRangeException
      *             If 't' is invalid
      * @throws IndexOutOfBoundsException