/*
 * Copyright (C) 2011 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.google.caliper;

/**
 * This is the class users must extend.
 * TODO(kevinb): full javadoc.
 */
public abstract class Benchmark {
  protected Benchmark() {}

  protected void setUp() throws Exception {}

  protected void tearDown() throws Exception {}
}

@@ -629,187 +629,2568 @@
 %0A * 
-This is the class users must extend.%0A * TODO(kevinb): full javadoc.%0A */%0Apublic abstract class Benchmark %7B%0A  protected Benchmark() %7B%7D%0A%0A  protected void setUp() throws Exception %7B%7D%0A
+Superclass for user benchmark classes to extend. To write a benchmark:%0A *%0A * %3Col%3E%0A *   %3Cli%3EExtend this class%0A *   %3Cli%3EAnnotate any fields with %7B@literal @%7D%7B@link Param%7D that should have parameter values%0A *      injected (see %7B@literal @%7D%7B@link Param%7D for more details)%0A *   %3Cli%3EOptionally override %7B@link #setUp setUp%7D and %7B@link #tearDown tearDown%7D%0A *   %3Cli%3EAdd one or more benchmark methods (for example, the standard microbenchmark instrument%0A *       recognizes a method beginning with the word %22time%22 and taking a single int or long%0A *       parameter as a benchmark method)%0A * %3C/ol%3E%0A *%0A * This class is instantiated and injected only once per child VM invocation, to measure one%0A * particular combination of parameters.%0A *%0A * For example: %3Cpre%3E   %7B@code%0A *   public class MyBenchmark extends Benchmark %7B%0A *     %7B@literal @%7DParam FeatureEnum feature;%0A *     %7B@literal @%7DParam(%7B%221%22, %2210%22, %22100%22%7D) int size;%0A *     private MyObject objectToBenchmark;%0A * %0A *     %7B@literal @%7DOverride protected void setUp() %7B%0A *       objectToBenchmark = new MyObject(size);%0A *     %7D%0A *%0A *     public int timeFoo(int reps) %7B%0A *       MyObject object = objectToBenchmark;  // copy to local to avoid field access overhead%0A *       int dummy = 0;%0A *       for (int i = 0; i %3C reps; i++) %7B%0A *         dummy += object.foo(feature);%0A *       %7D%0A *       // return a dummy value so the JIT compiler doesn't optimize away the entire method.%0A *       return dummy;%0A *     %7D%0A *%0A *     public int timeBar(int reps) %7B%0A *       // benchmark another operation of MyObject%0A *     %7D%0A *   %7D%0A * %3C/pre%3E%0A *%0A * The benchmark class MyBenchmark has two benchmark methods (%7B@code timeFoo%7D and %7B@code timeBar%7D)%0A * and two %7B@link Param Params%7D. For each experiment performed by caliper (e.g.%0A * %7B@code timeFoo%7D with %7B@code feature==FeatureEnum.A%7D and %7B@code size == 100%7D), %7B@link #setUp%7D will%0A * be called exactly once, but %7B@code timeFoo%7D may be called many times.%0A */%0Apublic abstract class Benchmark %7B%0A  protected Benchmark() %7B%7D%0A%0A  /**%0A   * Sets up the fixture. For example, generate some data structures.  The time it takes to run this%0A   * method will not be included in the benchmark time.%0A   *%0A   * %3Cp%3EBenchmarks can throw %7B@link com.google.caliper.api.SkipThisScenarioException%0A   * SkipThisScenarioException%7D if the particular combination of parameters injected into the%0A   * benchmark does not need to be measured.%0A   */%0A  protected void setUp() throws Exception %7B%7D%0A%0A  /**%0A   * Tears down the fixture. The time it takes to run this method will not be included in the%0A   * benchmark time.%0A   */
 %0A  p

Write some docs for Benchmark.java. There is probably a lot more that should be written (about different instruments, @FootPrint, etc.) but this is probably a good first step.