diff --git a/htrace-core/src/main/java/org/apache/htrace/Sampler.java b/htrace-core/src/main/java/org/apache/htrace/Sampler.java
index 9f81e14..45d8872 100644
--- a/htrace-core/src/main/java/org/apache/htrace/Sampler.java
+++ b/htrace-core/src/main/java/org/apache/htrace/Sampler.java
@@ -31,17 +31,20 @@
  * <p/>
  * For the example above, the next(T info) function may look like this
  * <p/>
- * public boolean next(T info){
- * if (info == null) {
- * return false;
- * } else if (info.getName().equals("get")) {
- * return Math.random() > 0.5;
- * } else if (info.getName().equals("put")) {
- * return Math.random() > 0.25;
- * } else {
- * return false;
+ * <pre>
+ * <code>public boolean next(T info) {
+ *   if (info == null) {
+ *     return false;
+ *   } else if (info.getName().equals("get")) {
+ *     return Math.random() > 0.5;
+ *   } else if (info.getName().equals("put")) {
+ *     return Math.random() > 0.25;
+ *   } else {
+ *     return false;
+ *   }
  * }
- * }
+ * </code>
+ * </pre>
  * This would trace 50% of all gets, 75% of all puts and would not trace any other requests.
  */
 public interface Sampler<T> {
diff --git a/htrace-core/src/main/java/org/apache/htrace/SamplerBuilder.java b/htrace-core/src/main/java/org/apache/htrace/SamplerBuilder.java
index 614a190..5d90e48 100644
--- a/htrace-core/src/main/java/org/apache/htrace/SamplerBuilder.java
+++ b/htrace-core/src/main/java/org/apache/htrace/SamplerBuilder.java
@@ -22,8 +22,18 @@
 import org.apache.htrace.impl.AlwaysSampler;
 import org.apache.htrace.impl.NeverSampler;
 
+/**
+ * A {@link Sampler} builder. It reads a {@link Sampler} class name from the provided
+ * configuration using the {@link #SAMPLER_CONF_KEY} key. Unqualified class names
+ * are interpreted as members of the {@code org.apache.htrace.impl} package. The {@link #build()}
+ * method constructs an instance of that class, initialized with the same configuration.
+ */
 public class SamplerBuilder {
-  private final static String SAMPLER_CONF_KEY = "sampler";
+
+  // TODO: should follow the same API as SpanReceiverBuilder
+
+  public final static String SAMPLER_CONF_KEY = "sampler";
+  private final static String DEFAULT_PACKAGE = "org.apache.htrace.impl";
   private final static ClassLoader classLoader =
       SamplerBuilder.class.getClassLoader();
   private final HTraceConfiguration conf;
@@ -39,7 +49,7 @@
       return NeverSampler.INSTANCE;
     }
     if (!str.contains(".")) {
-      str = "org.apache.htrace.impl." + str;
+      str = DEFAULT_PACKAGE + "." + str;
     }
     Class cls = null;
     try {
diff --git a/htrace-core/src/main/java/org/apache/htrace/SpanReceiver.java b/htrace-core/src/main/java/org/apache/htrace/SpanReceiver.java
index 22e8426..7ae157b 100644
--- a/htrace-core/src/main/java/org/apache/htrace/SpanReceiver.java
+++ b/htrace-core/src/main/java/org/apache/htrace/SpanReceiver.java
@@ -21,14 +21,19 @@
 
 
 /**
- * The collector within a process that is the destination of Spans when a trace
- * is running.
+ * The collector within a process that is the destination of Spans when a trace is running.
+ * {@code SpanReceiver} implementations are expected to provide a constructor with the signature
+ * <p>
+ * <pre>
+ * <code>public SpanReceiverImpl(HTraceConfiguration)</code>
+ * </pre>
+ * The helper class {@link org.apache.htrace.SpanReceiverBuilder} provides convenient factory
+ * methods for creating {@code SpanReceiver} instances from configuration.
+ * @see org.apache.htrace.SpanReceiverBuilder
  */
 public interface SpanReceiver extends Closeable {
   /**
    * Called when a Span is stopped and can now be stored.
-   *
-   * @param span
    */
   public void receiveSpan(Span span);
 }
diff --git a/htrace-core/src/main/java/org/apache/htrace/SpanReceiverBuilder.java b/htrace-core/src/main/java/org/apache/htrace/SpanReceiverBuilder.java
index 45d2872..cf6b050 100644
--- a/htrace-core/src/main/java/org/apache/htrace/SpanReceiverBuilder.java
+++ b/htrace-core/src/main/java/org/apache/htrace/SpanReceiverBuilder.java
@@ -21,13 +21,16 @@
 import org.apache.commons.logging.LogFactory;
 
 /**
- * A {@link SpanReceiver} builder. It defaults finding class of span receiver to build in
- * the passed in configuration using the {@link #SPAN_RECEIVER_CONF_KEY} key.
+ * A {@link SpanReceiver} builder. It reads a {@link SpanReceiver} class name from the provided
+ * configuration using the {@link #SPAN_RECEIVER_CONF_KEY} key. Unqualified class names
+ * are interpreted as members of the {@code org.apache.htrace.impl} package. The {@link #build()}
+ * method constructs an instance of that class, initialized with the same configuration.
  */
 public class SpanReceiverBuilder {
   static final Log LOG = LogFactory.getLog(SpanReceiverBuilder.class);
 
   public final static String SPAN_RECEIVER_CONF_KEY = "span.receiver";
+  private final static String DEFAULT_PACKAGE = "org.apache.htrace.impl";
   private final static ClassLoader classLoader =
       SpanReceiverBuilder.class.getClassLoader();
   private final HTraceConfiguration conf;
@@ -40,7 +43,8 @@
   }
 
   /**
-   * Set this builder back to defaults.
+   * Set this builder back to defaults. Any previous calls to {@link #spanReceiverClass(String)}
+   * are overridden by the value provided by configuration.
    * @return This instance
    */
   public SpanReceiverBuilder reset() {
@@ -49,6 +53,10 @@
     return this;
   }
 
+  /**
+   * Override the {@code SpanReceiver} class name provided in configuration with a new value.
+   * @return This instance
+   */
   public SpanReceiverBuilder spanReceiverClass(final String spanReceiverClass) {
     this.spanReceiverClass = spanReceiverClass;
     return this;
@@ -56,6 +64,7 @@
 
   /**
    * Configure whether we should log errors during build().
+   * @return This instance
    */
   public SpanReceiverBuilder logErrors(boolean logErrors) {
     this.logErrors = logErrors;
@@ -83,7 +92,7 @@
     }
     String str = spanReceiverClass;
     if (!str.contains(".")) {
-      str = "org.apache.htrace.impl." + str;
+      str = DEFAULT_PACKAGE + "." + str;
     }
     Class cls = null;
     try {
diff --git a/htrace-core/src/main/java/org/apache/htrace/impl/AlwaysSampler.java b/htrace-core/src/main/java/org/apache/htrace/impl/AlwaysSampler.java
index 69e3aff..7e0bf3b 100644
--- a/htrace-core/src/main/java/org/apache/htrace/impl/AlwaysSampler.java
+++ b/htrace-core/src/main/java/org/apache/htrace/impl/AlwaysSampler.java
@@ -19,6 +19,9 @@
 import org.apache.htrace.HTraceConfiguration;
 import org.apache.htrace.Sampler;
 
+/**
+ * A Sampler that always returns true.
+ */
 public final class AlwaysSampler implements Sampler<Object> {
 
   public static final AlwaysSampler INSTANCE = new AlwaysSampler(null);
diff --git a/htrace-core/src/main/java/org/apache/htrace/impl/CountSampler.java b/htrace-core/src/main/java/org/apache/htrace/impl/CountSampler.java
index 03b444b..fe98916 100644
--- a/htrace-core/src/main/java/org/apache/htrace/impl/CountSampler.java
+++ b/htrace-core/src/main/java/org/apache/htrace/impl/CountSampler.java
@@ -22,10 +22,11 @@
 import java.util.Random;
 
 /**
- * Sampler that returns true every N calls.
+ * Sampler that returns true every N calls. Specify the frequency interval by configuring a
+ * {@code long} value for {@link #SAMPLER_FREQUENCY_CONF_KEY}.
  */
 public class CountSampler implements Sampler<Object> {
-  private final static String SAMPLER_FREQUENCY_CONF_KEY = "sampler.frequency";
+  public final static String SAMPLER_FREQUENCY_CONF_KEY = "sampler.frequency";
 
   final static Random random = new Random();
 
diff --git a/htrace-core/src/main/java/org/apache/htrace/impl/NeverSampler.java b/htrace-core/src/main/java/org/apache/htrace/impl/NeverSampler.java
index 3ab192d..c633da7 100644
--- a/htrace-core/src/main/java/org/apache/htrace/impl/NeverSampler.java
+++ b/htrace-core/src/main/java/org/apache/htrace/impl/NeverSampler.java
@@ -19,6 +19,9 @@
 import org.apache.htrace.HTraceConfiguration;
 import org.apache.htrace.Sampler;
 
+/**
+ * A Sampler that never returns true.
+ */
 public final class NeverSampler implements Sampler<Object> {
 
   public static final NeverSampler INSTANCE = new NeverSampler(null);
diff --git a/htrace-core/src/main/java/org/apache/htrace/impl/ProbabilitySampler.java b/htrace-core/src/main/java/org/apache/htrace/impl/ProbabilitySampler.java
index c53d914..035a845 100644
--- a/htrace-core/src/main/java/org/apache/htrace/impl/ProbabilitySampler.java
+++ b/htrace-core/src/main/java/org/apache/htrace/impl/ProbabilitySampler.java
@@ -21,10 +21,14 @@
 
 import java.util.Random;
 
+/**
+ * Sampler that returns true a certain percentage of the time. Specify the frequency interval by
+ * configuring a {@code double} value for {@link #SAMPLER_FRACTION_CONF_KEY}.
+ */
 public class ProbabilitySampler implements Sampler<Object> {
   public final double threshold;
   private Random random = new Random();
-  private final static String SAMPLER_FRACTION_CONF_KEY = "sampler.fraction";
+  public final static String SAMPLER_FRACTION_CONF_KEY = "sampler.fraction";
 
   public ProbabilitySampler(HTraceConfiguration conf) {
     this.threshold = Double.parseDouble(conf.get(SAMPLER_FRACTION_CONF_KEY));
diff --git a/htrace-core/src/main/java/org/apache/htrace/impl/TrueIfTracingSampler.java b/htrace-core/src/main/java/org/apache/htrace/impl/TrueIfTracingSampler.java
index 7be7fc9..433a325 100644
--- a/htrace-core/src/main/java/org/apache/htrace/impl/TrueIfTracingSampler.java
+++ b/htrace-core/src/main/java/org/apache/htrace/impl/TrueIfTracingSampler.java
@@ -21,7 +21,7 @@
 import org.apache.htrace.Trace;
 
 /**
- * A Sampler that returns true if and only if tracing is on the current thread.
+ * A Sampler that returns true if and only if tracing is enabled for the current thread.
  */
 public class TrueIfTracingSampler implements Sampler<Object> {