Index: oak-run/src/main/java/org/apache/jackrabbit/oak/scalability/ScalabilityAbstractSuite.java
===================================================================
--- oak-run/src/main/java/org/apache/jackrabbit/oak/scalability/ScalabilityAbstractSuite.java	(revision 1595824)
+++ oak-run/src/main/java/org/apache/jackrabbit/oak/scalability/ScalabilityAbstractSuite.java	(working copy)
@@ -47,8 +47,24 @@
 import org.apache.jackrabbit.oak.fixture.RepositoryFixture;
 
 /**
- * Longevity suite to load test.
+ * Abstract class which defines a lot of the boiler-plate code needed to run the suite of tests.
  * 
+ * Any test suite extending from this class has the following entry points
+ * <p>
+ * {@link #beforeSuite()} - To configure the whole suite before the tests are started.
+ * <p>
+ * {@link #afterSuite()} - To shutdown the whole suite after all tests are finished.
+ * <p>
+ * {@link #beforeIteration(ExecutionContext)} - Any initialization to be performed before each of
+ * the test run. Typically, this can be configured to create additional loads for each iteration.
+ * This method will be called before each test iteration begins.
+ * <p>
+ * {@link #afterIteration()} - To configure any post test steps to be executed after each iteration
+ * of the test. This method will be called after each test iteration completes.
+ * <p>
+ * {@link #executeBenchmark(ScalabilityBenchmark, ExecutionContext)} - Actual benchmark/test to be
+ * executed. This method will be called in each iteration of the test run.
+ * 
  */
 public abstract class ScalabilityAbstractSuite implements ScalabilitySuite, CSVResultGenerator {
     /**
Index: oak-run/src/main/java/org/apache/jackrabbit/oak/scalability/ScalabilityBenchmark.java
===================================================================
--- oak-run/src/main/java/org/apache/jackrabbit/oak/scalability/ScalabilityBenchmark.java	(revision 1595824)
+++ oak-run/src/main/java/org/apache/jackrabbit/oak/scalability/ScalabilityBenchmark.java	(working copy)
@@ -25,8 +25,13 @@
 
 
 /**
- * Abstract class for all the Scalability/Longevity benchmarks.
+ * Base class for all the Scalability/Longevity benchmarks/tests.
  * 
+ * The implementations should implement the method
+ * {@link ScalabilityBenchmark#execute(Repository, Credentials, ExecutionContext)}.
+ * 
+ * This method will then be called from the {@link ScalabilitySuite} where configured.
+ * 
  */
 public abstract class ScalabilityBenchmark {
 
Index: oak-run/src/main/java/org/apache/jackrabbit/oak/scalability/ScalabilitySuite.java
===================================================================
--- oak-run/src/main/java/org/apache/jackrabbit/oak/scalability/ScalabilitySuite.java	(revision 1595824)
+++ oak-run/src/main/java/org/apache/jackrabbit/oak/scalability/ScalabilitySuite.java	(working copy)
@@ -23,7 +23,13 @@
 import org.apache.jackrabbit.oak.fixture.RepositoryFixture;
 
 /**
- * Interface for longevity suite for load testing.
+ * Interface for scalability suite for load testing.
+ * 
+ * {@link ScalabilitySuite} implementations would configure different {@link ScalabilityBenchmark}
+ * implementations for executing performance tests and measuring the execution times on those tests.
+ * 
+ * The entry method for the starting the tests is {@link #run(Iterable)}.
+ * 
  */
 public interface ScalabilitySuite {
     /**