core: document ServerBuilder return values and method history

Also, remove an erroneously added ExperimentalApi annotation.  The
method was non experimental as of the 1.0.0 release.

core/src/main/java/io/grpc/ServerBuilder.java

@@ -39,9 +39,16 @@ import javax.annotation.Nullable;
  * A builder for {@link Server} instances.
  *
  * @param <T> The concrete type of this builder.
+ * @since 1.0.0
  */
 public abstract class ServerBuilder<T extends ServerBuilder<T>> {
 
+  /**
+   * Static factory for creating a new ServerBuilder.
+   *
+   * @param port the port to listen on
+   * @since 1.0.0
+   */
   public static ServerBuilder<?> forPort(int port) {
     return ServerProvider.provider().builderForPort(port);
   }
@@ -56,6 +63,9 @@ public abstract class ServerBuilder<T extends ServerBuilder<T>> {
    * <p>Calling this method is semantically equivalent to calling {@link #executor(Executor)} and
    * passing in a direct executor. However, this is the preferred way as it may allow the transport
    * to perform special optimizations.
+   *
+   * @return this
+   * @since 1.0.0
    */
   public abstract T directExecutor();
 
@@ -67,6 +77,9 @@ public abstract class ServerBuilder<T extends ServerBuilder<T>> {
    *
    * <p>The server won't take ownership of the given executor. It's caller's responsibility to
    * shut down the executor when it's desired.
+   *
+   * @return this
+   * @since 1.0.0
    */
   public abstract T executor(@Nullable Executor executor);
 
@@ -74,6 +87,8 @@ public abstract class ServerBuilder<T extends ServerBuilder<T>> {
    * Adds a service implementation to the handler registry.
    *
    * @param service ServerServiceDefinition object
+   * @return this
+   * @since 1.0.0
    */
   public abstract T addService(ServerServiceDefinition service);
 
@@ -83,13 +98,17 @@ public abstract class ServerBuilder<T extends ServerBuilder<T>> {
    * server instance upon build().
    *
    * @param bindableService BindableService object
+   * @return this
+   * @since 1.0.0
    */
-  @ExperimentalApi("https://github.com/grpc/grpc-java/issues/2222")
   public abstract T addService(BindableService bindableService);
 
   /**
    * Adds a {@link ServerTransportFilter}. The order of filters being added is the order they will
    * be executed.
+   *
+   * @return this
+   * @since 1.2.0
    */
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/2132")
   public T addTransportFilter(ServerTransportFilter filter) {
@@ -99,6 +118,9 @@ public abstract class ServerBuilder<T extends ServerBuilder<T>> {
   /**
    * Adds a {@link ServerStreamTracer.Factory} to measure server-side traffic.  The order of
    * factories being added is the order they will be executed.
+   *
+   * @return this
+   * @since 1.3.0
    */
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/2861")
   public T addStreamTracerFactory(ServerStreamTracer.Factory factory) {
@@ -108,6 +130,9 @@ public abstract class ServerBuilder<T extends ServerBuilder<T>> {
   /**
    * Sets a fallback handler registry that will be looked up in if a method is not found in the
    * primary registry.
+   *
+   * @return this
+   * @since 1.0.0
    */
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/933")
   public abstract T fallbackHandlerRegistry(@Nullable HandlerRegistry fallbackRegistry);
@@ -117,6 +142,9 @@ public abstract class ServerBuilder<T extends ServerBuilder<T>> {
    *
    * @param certChain file containing the full certificate chain
    * @param privateKey file containing the private key
+   *
+   * @return this
+   * @since 1.0.0
    */
   public abstract T useTransportSecurity(File certChain, File privateKey);
 
@@ -124,6 +152,9 @@ public abstract class ServerBuilder<T extends ServerBuilder<T>> {
    * Set the decompression registry for use in the channel.  This is an advanced API call and
    * shouldn't be used unless you are using custom message encoding.   The default supported
    * decompressors are in {@code DecompressorRegistry.getDefaultInstance}.
+   *
+   * @return this
+   * @since 1.0.0
    */
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1704")
   public abstract T decompressorRegistry(@Nullable DecompressorRegistry registry);
@@ -132,6 +163,9 @@ public abstract class ServerBuilder<T extends ServerBuilder<T>> {
    * Set the compression registry for use in the channel.  This is an advanced API call and
    * shouldn't be used unless you are using custom message encoding.   The default supported
    * compressors are in {@code CompressorRegistry.getDefaultInstance}.
+   *
+   * @return this
+   * @since 1.0.0
    */
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1704")
   public abstract T compressorRegistry(@Nullable CompressorRegistry registry);
@@ -141,6 +175,9 @@ public abstract class ServerBuilder<T extends ServerBuilder<T>> {
    *
    * <p>The returned service will not been started or be bound a port. You will need to start it
    * with {@link Server#start()}.
+   *
+   * @return a new Server
+   * @since 1.0.0
    */
   public abstract Server build();
 }