tmf: Update comments in HistoryTree

Change-Id: Ic912058f261b042c88d772175b7d89f010b160cb
Signed-off-by: Alexandre Montplaisir <alexmonthy@voxpopuli.im>
Reviewed-on: https://git.eclipse.org/r/10636
Tested-by: Hudson CI
Reviewed-by: Bernd Hufmann <bhufmann@gmail.com>
IP-Clean: Bernd Hufmann <bhufmann@gmail.com>

diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/backends/historytree/HistoryTree.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/backends/historytree/HistoryTree.java
index ac04265bbef6b0d94c5c3301c6b6b7843659faed..4deb8a734c9a7566ee514e5710c027f1ea5db42a 100644 (file)
--- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/backends/historytree/HistoryTree.java
+++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/backends/historytree/HistoryTree.java
@@ -35,47 +35,52 @@ class HistoryTree {
 
     private static final int HISTORY_FILE_MAGIC_NUMBER = 0x05FFA900;
 
-    /**
+    /*
      * File format version. Increment minor on backwards-compatible changes.
      * Increment major + set minor back to 0 when breaking compatibility.
      */
     private static final int MAJOR_VERSION = 3;
     private static final byte MINOR_VERSION = 0;
 
-    /**
-     * Tree-specific configuration
-     */
-    /* Container for all the configuration constants */
+    // ------------------------------------------------------------------------
+    // Tree-specific configuration
+    // ------------------------------------------------------------------------
+
+    /** Container for all the configuration constants */
     protected final HTConfig config;
 
-    /* Reader/writer object */
+    /** Reader/writer object */
     private final HT_IO treeIO;
 
-    /**
-     * Variable Fields (will change throughout the existance of the SHT)
-     */
-    /* Latest timestamp found in the tree (at any given moment) */
+    // ------------------------------------------------------------------------
+    // Variable Fields (will change throughout the existance of the SHT)
+    // ------------------------------------------------------------------------
+
+    /** Latest timestamp found in the tree (at any given moment) */
     private long treeEnd;
 
-    /* How many nodes exist in this tree, total */
+    /** How many nodes exist in this tree, total */
     private int nodeCount;
 
-    /* "Cache" to keep the active nodes in memory */
+    /** "Cache" to keep the active nodes in memory */
     protected Vector<CoreNode> latestBranch;
 
+    // ------------------------------------------------------------------------
+    // Constructors/"Destructors"
+    // ------------------------------------------------------------------------
+
     /**
      * Create a new State History from scratch, using a SHTConfig object for
      * configuration
-     *
-     * @param conf
-     * @throws IOException
      */
     private HistoryTree(HTConfig conf) throws IOException {
         /*
-         * Simple assertion to make sure we have enough place in the 0th block
+         * Simple check to make sure we have enough place in the 0th block
          * for the tree configuration
          */
-        assert (conf.blockSize >= getTreeHeaderSize());
+        if (conf.blockSize < getTreeHeaderSize()) {
+            throw new IllegalArgumentException();
+        }
 
         config = conf;
         treeEnd = conf.treeStart;
@@ -91,11 +96,12 @@ class HistoryTree {
     }
 
     /**
-     * "New State History" constructor, which doesn't use SHTConfig but the
+     * "New State History" constructor, which doesn't use HTConfig but the
      * individual values separately. Kept for now for backwards compatibility,
      * but you should definitely consider using SHTConfig instead (since its
      * contents can then change without directly affecting SHT's API).
      */
+    @Deprecated
     HistoryTree(File newStateFile, int blockSize, int maxChildren,
             long startTime) throws IOException {
         this(new HTConfig(newStateFile, blockSize, maxChildren, startTime));
@@ -264,9 +270,9 @@ class HistoryTree {
         return;
     }
 
-    /**
-     * @name Accessors
-     */
+    // ------------------------------------------------------------------------
+    // Accessors
+    // ------------------------------------------------------------------------
 
     long getTreeStart() {
         return config.treeStart;
@@ -284,6 +290,10 @@ class HistoryTree {
         return treeIO;
     }
 
+    // ------------------------------------------------------------------------
+    // Operations
+    // ------------------------------------------------------------------------
+
     /**
      * Rebuild the latestBranch "cache" object by reading the nodes from disk
      * (When we are opening an existing file on disk and want to append to it,