tmf.ui: Add extra javadoc to the AbstractTimeGraphView

This adds some documentation to the AbstractTimeGraphView#buildEntryList
method.

Change-Id: Ia33479198efa3883d872fb69c8dde17e6930241e
Signed-off-by: Geneviève Bastien <gbastien+lttng@versatic.net>
Reviewed-on: https://git.eclipse.org/r/80931
Reviewed-by: Patrick Tasse <patrick.tasse@gmail.com>
Tested-by: Patrick Tasse <patrick.tasse@gmail.com>
Reviewed-by: Hudson CI

diff --git a/tmf/org.eclipse.tracecompass.tmf.ui/src/org/eclipse/tracecompass/tmf/ui/views/timegraph/AbstractTimeGraphView.java b/tmf/org.eclipse.tracecompass.tmf.ui/src/org/eclipse/tracecompass/tmf/ui/views/timegraph/AbstractTimeGraphView.java
index f1414d453e9167c4a72577bd6815d2b288873e92..1a2cc5df578d2640678f41efece55179964221d8 100644 (file)
--- a/tmf/org.eclipse.tracecompass.tmf.ui/src/org/eclipse/tracecompass/tmf/ui/views/timegraph/AbstractTimeGraphView.java
+++ b/tmf/org.eclipse.tracecompass.tmf.ui/src/org/eclipse/tracecompass/tmf/ui/views/timegraph/AbstractTimeGraphView.java
@@ -1701,8 +1701,29 @@ public abstract class AbstractTimeGraphView extends TmfView implements ITmfTimeA
      * Build the entry list to show in this time graph view.
      * <p>
      * Called from the BuildJob for each trace returned by
-     * {@link #getTracesToBuild(ITmfTrace)}. The full event list is also
-     * normally computed for every entry that is created.
+     * {@link #getTracesToBuild(ITmfTrace)}.
+     * <p>
+     * Root entries must be added to the entry list by calling the
+     * {@link #addToEntryList(ITmfTrace, List)} method with the list of entries
+     * to add and where the trace in parameter should be the parentTrace.
+     * Entries that are children of other entries will be automatically picked
+     * up after refreshing the root entries.
+     * <p>
+     * The full event list is also normally computed for every entry that is
+     * created. It should be set for each entry by calling the
+     * {@link TimeGraphEntry#setEventList(List)}. These full event lists will be
+     * used to display something while the zoomed event lists are being
+     * calculated when the window range is updated. Also, when fully zoomed out,
+     * it is this list of events that is displayed.
+     * <p>
+     * Also, when all the entries have been added and their events set, this
+     * method can finish by calling the refresh() method like this:
+     *
+     * <pre>
+     * if (parentTrace.equals(getTrace())) {
+     *     refresh();
+     * }
+     * </pre>
      *
      * @param trace
      *            The trace being built