SPARK-1093: Annotate developer and experimental API's

core/src/main/scala/org/apache/spark/Aggregator.scala

@@ -20,6 +20,8 @@ package org.apache.spark
 import org.apache.spark.util.collection.{AppendOnlyMap, ExternalAppendOnlyMap}
 
 /**
+ * <span class="badge badge-red" style="float: right;">DEVELOPER API - UNSTABLE</span>
+ *
  * A set of functions used to aggregate data.
  *
  * @param createCombiner function to create the initial value of the aggregation.

core/src/main/scala/org/apache/spark/Dependency.scala

@@ -21,12 +21,16 @@ import org.apache.spark.rdd.RDD
 import org.apache.spark.serializer.Serializer
 
 /**
+ * <span class="badge badge-red" style="float: right;">DEVELOPER API - UNSTABLE</span>
+ *
  * Base class for dependencies.
  */
 abstract class Dependency[T](val rdd: RDD[T]) extends Serializable
 
 
 /**
+ * <span class="badge badge-red" style="float: right;">DEVELOPER API - UNSTABLE</span>
+ *
  * Base class for dependencies where each partition of the parent RDD is used by at most one
  * partition of the child RDD.  Narrow dependencies allow for pipelined execution.
  */
@@ -41,6 +45,8 @@ abstract class NarrowDependency[T](rdd: RDD[T]) extends Dependency(rdd) {
 
 
 /**
+ * <span class="badge badge-red" style="float: right;">DEVELOPER API - UNSTABLE</span>
+ *
  * Represents a dependency on the output of a shuffle stage.
  * @param rdd the parent RDD
  * @param partitioner partitioner used to partition the shuffle output
@@ -59,6 +65,8 @@ class ShuffleDependency[K, V](
 
 
 /**
+ * <span class="badge badge-red" style="float: right;">DEVELOPER API - UNSTABLE</span>
+ *
  * Represents a one-to-one dependency between partitions of the parent and child RDDs.
  */
 class OneToOneDependency[T](rdd: RDD[T]) extends NarrowDependency[T](rdd) {
@@ -67,6 +75,8 @@ class OneToOneDependency[T](rdd: RDD[T]) extends NarrowDependency[T](rdd) {
 
 
 /**
+ * <span class="badge badge-red" style="float: right;">DEVELOPER API - UNSTABLE</span>
+ *
  * Represents a one-to-one dependency between ranges of partitions in the parent and child RDDs.
  * @param rdd the parent RDD
  * @param inStart the start of the range in the parent RDD

core/src/main/scala/org/apache/spark/FutureAction.scala

@@ -25,6 +25,8 @@ import org.apache.spark.rdd.RDD
 import org.apache.spark.scheduler.{JobFailed, JobSucceeded, JobWaiter}
 
 /**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL API</span>
+ *
  * A future for the result of an action to support cancellation. This is an extension of the
  * Scala Future interface to support cancellation.
  */
@@ -148,6 +150,8 @@ class SimpleFutureAction[T] private[spark](jobWaiter: JobWaiter[_], resultFunc:
 
 
 /**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL API</span>
+ *
  * A [[FutureAction]] for actions that could trigger multiple Spark jobs. Examples include take,
  * takeSample. Cancellation works by setting the cancelled flag to true and interrupting the
  * action thread if it is being blocked by a job.

core/src/main/scala/org/apache/spark/SerializableWritable.scala

@@ -23,7 +23,7 @@ import org.apache.hadoop.conf.Configuration
 import org.apache.hadoop.io.ObjectWritable
 import org.apache.hadoop.io.Writable
 
-class SerializableWritable[T <: Writable](@transient var t: T) extends Serializable {
+private[spark] class SerializableWritable[T <: Writable](@transient var t: T) extends Serializable {
   def value = t
   override def toString = t.toString
 

core/src/main/scala/org/apache/spark/SparkEnv.scala

@@ -41,7 +41,7 @@ import org.apache.spark.util.{AkkaUtils, Utils}
  * objects needs to have the right SparkEnv set. You can get the current environment with
  * SparkEnv.get (e.g. after creating a SparkContext) and set it with SparkEnv.set.
  */
-class SparkEnv private[spark] (
+private[spark] class SparkEnv (
     val executorId: String,
     val actorSystem: ActorSystem,
     val serializer: Serializer,

core/src/main/scala/org/apache/spark/TaskContext.scala

@@ -21,6 +21,11 @@ import scala.collection.mutable.ArrayBuffer
 
 import org.apache.spark.executor.TaskMetrics
 
+/**
+ * <span class="badge badge-red" style="float: right;">DEVELOPER API - UNSTABLE</span>
+ *
+ * Contextual information about a task which can be read or mutated during execution.
+ */
 class TaskContext(
   val stageId: Int,
   val partitionId: Int,

core/src/main/scala/org/apache/spark/api/java/JavaUtils.scala

@@ -19,7 +19,7 @@ package org.apache.spark.api.java
 
 import com.google.common.base.Optional
 
-object JavaUtils {
+private[spark] object JavaUtils {
   def optionToOptional[T](option: Option[T]): Optional[T] =
     option match {
       case Some(value) => Optional.of(value)

core/src/main/scala/org/apache/spark/executor/ExecutorSource.scala

@@ -24,7 +24,7 @@ import org.apache.hadoop.fs.FileSystem
 
 import org.apache.spark.metrics.source.Source
 
-class ExecutorSource(val executor: Executor, executorId: String) extends Source {
+private[spark] class ExecutorSource(val executor: Executor, executorId: String) extends Source {
   private def fileStats(scheme: String) : Option[FileSystem.Statistics] =
     FileSystem.getAllStatistics().filter(s => s.getScheme.equals(scheme)).headOption
 

core/src/main/scala/org/apache/spark/executor/TaskMetrics.scala

@@ -19,6 +19,11 @@ package org.apache.spark.executor
 
 import org.apache.spark.storage.{BlockId, BlockStatus}
 
+/**
+ * <span class="badge badge-red" style="float: right;">DEVELOPER API - UNSTABLE</span>
+ *
+ * Metrics tracked during the execution of a task.
+ */
 class TaskMetrics extends Serializable {
   /**
    * Host's name the task runs on
@@ -82,6 +87,11 @@ object TaskMetrics {
 }
 
 
+/**
+ * <span class="badge badge-red" style="float: right;">DEVELOPER API - UNSTABLE</span>
+ *
+ * Metrics pertaining to shuffle data read in a given task.
+ */
 class ShuffleReadMetrics extends Serializable {
   /**
    * Absolute time when this task finished reading shuffle data
@@ -116,6 +126,11 @@ class ShuffleReadMetrics extends Serializable {
   var remoteBytesRead: Long = _
 }
 
+/**
+ * <span class="badge badge-red" style="float: right;">DEVELOPER API - UNSTABLE</span>
+ *
+ * Metrics pertaining to shuffle data written in a given task.
+ */
 class ShuffleWriteMetrics extends Serializable {
   /**
    * Number of bytes written for the shuffle by this task

core/src/main/scala/org/apache/spark/io/CompressionCodec.scala

@@ -25,8 +25,14 @@ import org.xerial.snappy.{SnappyInputStream, SnappyOutputStream}
 import org.apache.spark.SparkConf
 
 /**
+ * <span class="badge badge-red" style="float: right;">DEVELOPER API - UNSTABLE</span>
+ *
  * CompressionCodec allows the customization of choosing different compression implementations
  * to be used in block storage.
+ *
+ * Note: The wire protocol for a codec is not guaranteed compatible across versions of Spark.
+ *       This is intended for use as an internal compression utility within a single
+ *       Spark application.
  */
 trait CompressionCodec {
 
@@ -52,7 +58,13 @@ private[spark] object CompressionCodec {
 
 
 /**
+ * <span class="badge badge-red" style="float: right;">DEVELOPER API - UNSTABLE</span>
+ *
  * LZF implementation of [[org.apache.spark.io.CompressionCodec]].
+ *
+ * Note: The wire protocol for this codec is not guaranteed to be compatible across versions
+ *       of Spark. This is intended for use as an internal compression utility within a single Spark
+ *       application.
  */
 class LZFCompressionCodec(conf: SparkConf) extends CompressionCodec {
 
@@ -65,8 +77,14 @@ class LZFCompressionCodec(conf: SparkConf) extends CompressionCodec {
 
 
 /**
+ * <span class="badge badge-red" style="float: right;">DEVELOPER API - UNSTABLE</span>
+ *
  * Snappy implementation of [[org.apache.spark.io.CompressionCodec]].
  * Block size can be configured by spark.io.compression.snappy.block.size.
+ *
+ * Note: The wire protocol for this codec is not guaranteed to be compatible across versions
+ *       of Spark. This is intended for use as an internal compression utility within a single Spark
+ *       application.
  */
 class SnappyCompressionCodec(conf: SparkConf) extends CompressionCodec {
 

core/src/main/scala/org/apache/spark/metrics/sink/ConsoleSink.scala

@@ -25,7 +25,7 @@ import com.codahale.metrics.{ConsoleReporter, MetricRegistry}
 import org.apache.spark.SecurityManager
 import org.apache.spark.metrics.MetricsSystem
 
-class ConsoleSink(val property: Properties, val registry: MetricRegistry,
+private[spark] class ConsoleSink(val property: Properties, val registry: MetricRegistry,
     securityMgr: SecurityManager) extends Sink {
   val CONSOLE_DEFAULT_PERIOD = 10
   val CONSOLE_DEFAULT_UNIT = "SECONDS"

core/src/main/scala/org/apache/spark/metrics/sink/CsvSink.scala

@@ -26,7 +26,7 @@ import com.codahale.metrics.{CsvReporter, MetricRegistry}
 import org.apache.spark.SecurityManager
 import org.apache.spark.metrics.MetricsSystem
 
-class CsvSink(val property: Properties, val registry: MetricRegistry,
+private[spark] class CsvSink(val property: Properties, val registry: MetricRegistry,
     securityMgr: SecurityManager) extends Sink {
   val CSV_KEY_PERIOD = "period"
   val CSV_KEY_UNIT = "unit"

core/src/main/scala/org/apache/spark/metrics/sink/GraphiteSink.scala

@@ -27,7 +27,7 @@ import com.codahale.metrics.graphite.{Graphite, GraphiteReporter}
 import org.apache.spark.SecurityManager
 import org.apache.spark.metrics.MetricsSystem
 
-class GraphiteSink(val property: Properties, val registry: MetricRegistry,
+private[spark] class GraphiteSink(val property: Properties, val registry: MetricRegistry,
     securityMgr: SecurityManager) extends Sink {
   val GRAPHITE_DEFAULT_PERIOD = 10
   val GRAPHITE_DEFAULT_UNIT = "SECONDS"

core/src/main/scala/org/apache/spark/metrics/sink/JmxSink.scala

@@ -22,7 +22,7 @@ import java.util.Properties
 import com.codahale.metrics.{JmxReporter, MetricRegistry}
 import org.apache.spark.SecurityManager
 
-class JmxSink(val property: Properties, val registry: MetricRegistry,
+private[spark] class JmxSink(val property: Properties, val registry: MetricRegistry,
     securityMgr: SecurityManager) extends Sink {
 
   val reporter: JmxReporter = JmxReporter.forRegistry(registry).build()

core/src/main/scala/org/apache/spark/metrics/sink/MetricsServlet.scala

@@ -30,7 +30,7 @@ import org.eclipse.jetty.servlet.ServletContextHandler
 import org.apache.spark.SecurityManager
 import org.apache.spark.ui.JettyUtils._
 
-class MetricsServlet(val property: Properties, val registry: MetricRegistry,
+private[spark] class MetricsServlet(val property: Properties, val registry: MetricRegistry,
     securityMgr: SecurityManager) extends Sink {
   val SERVLET_KEY_PATH = "path"
   val SERVLET_KEY_SAMPLE = "sample"

core/src/main/scala/org/apache/spark/metrics/sink/Sink.scala

@@ -17,7 +17,7 @@
 
 package org.apache.spark.metrics.sink
 
-trait Sink {
+private[spark] trait Sink {
   def start: Unit
   def stop: Unit
 }

core/src/main/scala/org/apache/spark/metrics/source/JvmSource.scala

@@ -20,7 +20,7 @@ package org.apache.spark.metrics.source
 import com.codahale.metrics.MetricRegistry
 import com.codahale.metrics.jvm.{GarbageCollectorMetricSet, MemoryUsageGaugeSet}
 
-class JvmSource extends Source {
+private[spark] class JvmSource extends Source {
   val sourceName = "jvm"
   val metricRegistry = new MetricRegistry()
 

core/src/main/scala/org/apache/spark/metrics/source/Source.scala

@@ -19,7 +19,7 @@ package org.apache.spark.metrics.source
 
 import com.codahale.metrics.MetricRegistry
 
-trait Source {
+private[spark] trait Source {
   def sourceName: String
   def metricRegistry: MetricRegistry
 }

core/src/main/scala/org/apache/spark/partial/BoundedDouble.scala

@@ -18,7 +18,9 @@
 package org.apache.spark.partial
 
 /**
- * A Double with error bars on it.
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL API</span>
+ *
+ * A Double value with error bars and associated confidence.
  */
 class BoundedDouble(val mean: Double, val confidence: Double, val low: Double, val high: Double) {
   override def toString(): String = "[%.3f, %.3f]".format(low, high)

core/src/main/scala/org/apache/spark/partial/PartialResult.scala

@@ -17,6 +17,9 @@
 
 package org.apache.spark.partial
 
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL API</span>
+ */
 class PartialResult[R](initialVal: R, isFinal: Boolean) {
   private var finalValue: Option[R] = if (isFinal) Some(initialVal) else None
   private var failure: Option[Exception] = None

core/src/main/scala/org/apache/spark/rdd/AsyncRDDActions.scala

@@ -26,6 +26,8 @@ import scala.reflect.ClassTag
 import org.apache.spark.{ComplexFutureAction, FutureAction, Logging}
 
 /**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL API</span>
+ *
  * A set of asynchronous RDD actions available through an implicit conversion.
  * Import `org.apache.spark.SparkContext._` at the top of your program to use these functions.
  */

core/src/main/scala/org/apache/spark/rdd/CoGroupedRDD.scala

@@ -57,6 +57,7 @@ private[spark] class CoGroupPartition(idx: Int, val deps: Array[CoGroupSplitDep]
  * @param rdds parent RDDs.
  * @param part partitioner used to partition the shuffle output.
  */
+private[spark]
 class CoGroupedRDD[K](@transient var rdds: Seq[RDD[_ <: Product2[K, _]]], part: Partitioner)
   extends RDD[(K, Seq[Seq[_]])](rdds.head.context, Nil) {
 

core/src/main/scala/org/apache/spark/rdd/CoalescedRDD.scala

@@ -32,7 +32,7 @@ import org.apache.spark._
  * @param parentsIndices list of indices in the parent that have been coalesced into this partition
  * @param preferredLocation the preferred location for this partition
  */
-case class CoalescedRDDPartition(
+private[spark] case class CoalescedRDDPartition(
                                   index: Int,
                                   @transient rdd: RDD[_],
                                   parentsIndices: Array[Int],
@@ -70,7 +70,7 @@ case class CoalescedRDDPartition(
  * @param maxPartitions number of desired partitions in the coalesced RDD
  * @param balanceSlack used to trade-off balance and locality. 1.0 is all locality, 0 is all balance
  */
-class CoalescedRDD[T: ClassTag](
+private[spark] class CoalescedRDD[T: ClassTag](
                                       @transient var prev: RDD[T],
                                       maxPartitions: Int,
                                       balanceSlack: Double = 0.10)

core/src/main/scala/org/apache/spark/rdd/EmptyRDD.scala

@@ -24,7 +24,7 @@ import org.apache.spark.{Partition, SparkContext, TaskContext}
 /**
  * An RDD that is empty, i.e. has no element in it.
  */
-class EmptyRDD[T: ClassTag](sc: SparkContext) extends RDD[T](sc, Nil) {
+private[spark] class EmptyRDD[T: ClassTag](sc: SparkContext) extends RDD[T](sc, Nil) {
 
   override def getPartitions: Array[Partition] = Array.empty
 

core/src/main/scala/org/apache/spark/rdd/HadoopRDD.scala

@@ -70,9 +70,14 @@ private[spark] class HadoopPartition(rddId: Int, idx: Int, @transient s: InputSp
 }
 
 /**
+ * <span class="badge badge-red" style="float: right;">DEVELOPER API - UNSTABLE</span>
+ *
  * An RDD that provides core functionality for reading data stored in Hadoop (e.g., files in HDFS,
  * sources in HBase, or S3), using the older MapReduce API (`org.apache.hadoop.mapred`).
  *
+ * Note: Instantiating this class directly is not recommended, please use
+ * [[org.apache.spark.SparkContext.hadoopRDD()]]
+ *
  * @param sc The SparkContext to associate the RDD with.
  * @param broadcastedConf A general Hadoop Configuration, or a subclass of it. If the enclosed
  *     variabe references an instance of JobConf, then that JobConf will be used for the Hadoop job.

core/src/main/scala/org/apache/spark/rdd/JdbcRDD.scala

@@ -27,7 +27,7 @@ import org.apache.spark.util.NextIterator
 private[spark] class JdbcPartition(idx: Int, val lower: Long, val upper: Long) extends Partition {
   override def index = idx
 }
-
+// TODO: Expose a jdbcRDD function in SparkContext and mark this as semi-private
 /**
  * An RDD that executes an SQL query on a JDBC connection and reads results.
  * For usage example, see test case JdbcRDDSuite.

core/src/main/scala/org/apache/spark/rdd/NewHadoopRDD.scala

@@ -36,9 +36,14 @@ class NewHadoopPartition(rddId: Int, val index: Int, @transient rawSplit: InputS
 }
 
 /**
+ * <span class="badge badge-red" style="float: right;">DEVELOPER API - UNSTABLE</span>
+ *
  * An RDD that provides core functionality for reading data stored in Hadoop (e.g., files in HDFS,
  * sources in HBase, or S3), using the new MapReduce API (`org.apache.hadoop.mapreduce`).
  *
+ * Note: Instantiating this class directly is not recommended, please use
+ * [[org.apache.spark.SparkContext.newAPIHadoopRDD()]]
+ *
  * @param sc The SparkContext to associate the RDD with.
  * @param inputFormatClass Storage format of the data to be read.
  * @param keyClass Class of the key associated with the inputFormatClass.