--- a/jdk/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpRequest.java	Wed Apr 26 16:05:55 2017 -0700
+++ b/jdk/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpRequest.java	Thu Apr 27 12:38:21 2017 +0100
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -355,7 +355,7 @@
          * of not setting a timeout is the same as setting an infinite Duration, ie.
          * block forever.
          *
-         * @param duration
+         * @param duration the timeout duration
          * @return this request builder
          */
         public abstract Builder timeout(Duration duration);

--- a/jdk/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpResponse.java	Wed Apr 26 16:05:55 2017 -0700
+++ b/jdk/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpResponse.java	Thu Apr 27 12:38:21 2017 +0100
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -224,7 +224,7 @@
     public interface BodyHandler<T> {
 
         /**
-         * Return a {@link BodyProcessor BodyProcessor} considering the given response status
+         * Returns a {@link BodyProcessor BodyProcessor} considering the given response status
          * code and headers. This method is always called before the body is read
          * and its implementation can decide to keep the body and store it somewhere
          * or else discard it, by  returning the {@code BodyProcessor} returned
@@ -232,7 +232,7 @@
          *
          * @param statusCode the HTTP status code received
          * @param responseHeaders the response headers received
-         * @return
+         * @return a response body handler
          */
         public BodyProcessor<T> apply(int statusCode, HttpHeaders responseHeaders);
 
@@ -242,7 +242,7 @@
          *
          * @param <U> the response body type
          * @param value the value of U to return as the body
-         * @return
+         * @return a response body handler
          */
         public static <U> BodyHandler<U> discard(U value) {
             return (status, headers) -> BodyProcessor.discard(value);
@@ -260,7 +260,7 @@
          *
          * @param charset the name of the charset to interpret the body as. If
          * {@code null} then charset determined from Content-encoding header
-         * @return a response handler
+         * @return a response body handler
          */
         public static BodyHandler<String> asString(Charset charset) {
             return (status, headers) -> {
@@ -282,7 +282,7 @@
          * {@link Path}.
          *
          * @param file the file to store the body in
-         * @return a response handler
+         * @return a response body handler
          */
         public static BodyHandler<Path> asFile(Path file) {
             return (status, headers) -> BodyProcessor.asFile(file);
@@ -306,7 +306,7 @@
          *
          * @param directory the directory to store the file in
          * @param openOptions open options
-         * @return a response handler
+         * @return a response body handler
          */
         public static BodyHandler<Path> asFileDownload(Path directory, OpenOption... openOptions) {
             return (status, headers) -> {
@@ -343,7 +343,7 @@
          *
          * @param file the filename to store the body in
          * @param openOptions any options to use when opening/creating the file
-         * @return a response handler
+         * @return a response body handler
          */
         public static BodyHandler<Path> asFile(Path file, OpenOption... openOptions) {
             return (status, headers) -> BodyProcessor.asFile(file, openOptions);
@@ -359,7 +359,7 @@
          * written to the consumer.
          *
          * @param consumer a Consumer to accept the response body
-         * @return a a response handler
+         * @return a response body handler
          */
         public static BodyHandler<Void> asByteArrayConsumer(Consumer<Optional<byte[]>> consumer) {
             return (status, headers) -> BodyProcessor.asByteArrayConsumer(consumer);
@@ -373,7 +373,7 @@
          * When the {@code HttpResponse} object is returned, the body has been completely
          * written to the byte array.
          *
-         * @return a response handler
+         * @return a response body handler
          */
         public static BodyHandler<byte[]> asByteArray() {
             return (status, headers) -> BodyProcessor.asByteArray();
@@ -392,7 +392,7 @@
          * When the {@code HttpResponse} object is returned, the body has been completely
          * written to the string.
          *
-         * @return a response handler
+         * @return a response body handler
          */
         public static BodyHandler<String> asString() {
             return (status, headers) -> BodyProcessor.asString(charsetFrom(headers));
@@ -606,7 +606,7 @@
          * either one of onResponse() or onError() is guaranteed to be called,
          * but not both.
          *
-         * @param request
+         * @param request the main request or subsequent push promise
          * @param t the Throwable that caused the error
          */
         void onError(HttpRequest request, Throwable t);
@@ -717,7 +717,7 @@
          * join() call returns, all {@code HttpResponse}s and their associated
          * body objects are available.
          *
-         * @param <V>
+         * @param <V> the body type used for all responses
          * @param pushHandler a function invoked for each request or push
          * promise
          * @return a MultiProcessor