--- old/src/share/vm/gc/g1/g1IHOPControl.hpp	2015-11-16 16:53:04.437401485 +0100
+++ new/src/share/vm/gc/g1/g1IHOPControl.hpp	2015-11-16 16:53:04.349398837 +0100
@@ -26,14 +26,15 @@
 #define SHARE_VM_GC_G1_G1IHOPCONTROL_HPP
 
 #include "memory/allocation.hpp"
-#include "utilities/numberSeq.hpp"
 
-class G1Predictions;
-
-// Manages the decision about the threshold when concurrent marking should start.
+// Base class for algorithms that calculate the heap occupancy at which
+// concurrent marking should start. This heap usage threshold should be relative
+// to old gen size.
 class G1IHOPControl : public CHeapObj<mtGC> {
  protected:
-  double _ihop_percent;
+  // The initial IHOP value relative to the target occupancy.
+  double _initial_ihop_percent;
+  // The target maximum occupancy of the heap.
   size_t _target_occupancy;
 
   // Initialize an instance with the initial IHOP value in percent and the target
@@ -43,26 +44,39 @@
  public:
   virtual ~G1IHOPControl() { }
 
-  // Get the current marking threshold in bytes.
+  // Get the current non-young occupancy at which concurrent marking should start.
   virtual size_t get_conc_mark_start_threshold() = 0;
 
-  // Update information about recent time during which allocations happened,
-  // how many allocations happened and an additional safety buffer.
+  // Update information about time during which allocations in the Java heap occurred,
+  // how large these allocations were in bytes, and an additional buffer.
+  // The allocations should contain any amount of space made unusable for further
+  // allocation, e.g. any waste caused by TLAB allocation, space at the end of
+  // humongous objects that can not be used for allocation, etc.
+  // Together with the target occupancy, this additional buffer should contain the
+  // difference between old gen size and total heap size at the start of reclamation,
+  // and space required for that reclamation.
   virtual void update_allocation_info(double allocation_time_s, size_t allocated_bytes, size_t additional_buffer_size) = 0;
-  // Update the time from the end of initial mark to the first mixed gc.
-  virtual void update_time_to_mixed(double marking_length_s) = 0;
+  // Update the time spent in the mutator beginning from the end of initial mark to
+  // the first mixed gc.
+  virtual void update_marking_length(double marking_length_s) = 0;
 
   virtual void print() = 0;
 };
 
+// The returned concurrent mark starting occupancy threshold is a fixed value
+// relative to the maximum heap size.
 class G1StaticIHOPControl : public G1IHOPControl {
+  // Most recent complete mutator allocation period in seconds.
   double _last_allocation_time_s;
+  // Amount of bytes allocated during _last_allocation_time_s.
   size_t _last_allocated_bytes;
+  // Most recent mutator time between the end of initial mark to the start of the
+  // first mixed gc.
   double _last_marking_length_s;
  public:
   G1StaticIHOPControl(double ihop_percent, size_t target_occupancy);
 
-  size_t get_conc_mark_start_threshold() { return (size_t) (_ihop_percent * _target_occupancy / 100.0); }
+  size_t get_conc_mark_start_threshold() { return (size_t) (_initial_ihop_percent * _target_occupancy / 100.0); }
 
   virtual void update_allocation_info(double allocation_time_s, size_t allocated_bytes, size_t additional_buffer_size) {
     assert(allocation_time_s >= 0.0, "Allocation time must be positive but is %.3f", allocation_time_s);
@@ -70,7 +84,7 @@
     _last_allocated_bytes = allocated_bytes;
   }
 
-  virtual void update_time_to_mixed(double marking_length_s) {
+  virtual void update_marking_length(double marking_length_s) {
    assert(marking_length_s > 0.0, "Marking length must be larger than zero but is %.3f", marking_length_s);
     _last_marking_length_s = marking_length_s;
   }