This closes #3033

Author: tgroh

sdks/java/core/src/main/java/org/apache/beam/sdk/values/PValue.java

@@ -18,13 +18,15 @@
 package org.apache.beam.sdk.values;
 
 import java.util.Map;
+import org.apache.beam.sdk.annotations.Internal;
 import org.apache.beam.sdk.transforms.PTransform;
 
 /**
- * The interface for values that can be input to and output from {@link PTransform PTransforms}.
+ * <b><i>For internal use. No backwards compatibility guarantees.</i></b>
  *
- * <p>It is recommended to extend {@link PValueBase}
+ * <p>A primitive value within Beam.
  */
+@Internal
 public interface PValue extends POutput, PInput {
 
   /**
@@ -45,13 +47,13 @@ public interface PValue extends POutput, PInput {
    * After building, finalizes this {@code PValue} to make it ready for being used as an input to a
    * {@link org.apache.beam.sdk.transforms.PTransform}.
    *
-   * <p>Automatically invoked whenever {@code apply()} is invoked on this {@code PValue}, after
-   * {@link PValue#finishSpecifying(PInput, PTransform)} has been called on each component {@link
-   * PValue}, so users do not normally call this explicitly.
+   * <p>Automatically invoked whenever {@code apply()} is invoked on this {@code PValue}. Users
+   * should not normally call this explicitly.
    *
    * @param upstreamInput the {@link PInput} the {@link PTransform} was applied to to produce this
    *     output
    * @param upstreamTransform the {@link PTransform} that produced this {@link PValue}
    */
+  @Internal
   void finishSpecifying(PInput upstreamInput, PTransform<?, ?> upstreamTransform);
 }

sdks/java/core/src/main/java/org/apache/beam/sdk/values/PValueBase.java

@@ -22,22 +22,17 @@
 import java.util.Collections;
 import java.util.Map;
 import org.apache.beam.sdk.Pipeline;
+import org.apache.beam.sdk.annotations.Internal;
 import org.apache.beam.sdk.transforms.PTransform;
 import org.apache.beam.sdk.util.NameUtils;
 
 /**
- * A {@link PValueBase} is an abstract base class that provides
- * sensible default implementations for methods of {@link PValue}.
- * In particular, this includes functionality for getting/setting:
+ * <b><i>For internal use. No backwards compatibility guarantees.</i></b>
  *
- * <ul>
- *   <li> The {@link Pipeline} that the {@link PValue} is part of.</li>
- *   <li> Whether the {@link PValue} has bee finalized (as an input
- *     or an output), after which its properties can no longer be changed.</li>
- * </ul>
- *
- * <p>For internal use.
+ * <p>An abstract base class that provides default implementations for some methods of
+ * {@link PValue}.
  */
+@Internal
 public abstract class PValueBase implements PValue {
 
   private final Pipeline pipeline;