--- a/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpRequest.java	Fri Nov 17 16:34:05 2017 +0000
+++ b/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpRequest.java	Fri Nov 17 17:34:58 2017 +0000
@@ -338,6 +338,7 @@
 
         /**
          * Adds the given name value pair to the set of headers for this request.
+         * The given value is added to the list of values for that name.
          *
          * @param name the header name
          * @param value the header value
@@ -352,6 +353,8 @@
          * Adds the given name value pairs to the set of headers for this
          * request. The supplied {@code String} instances must alternate as
          * header names and header values.
+         * To add several values to the same name then the same name must
+         * be supplied with each new value.
          *
          * @param headers the list of name value pairs
          * @return this request builder