diff --git a/pkgs/http/CHANGELOG.md b/pkgs/http/CHANGELOG.md
index 7926fa761a..6ac3263fb6 100644
--- a/pkgs/http/CHANGELOG.md
+++ b/pkgs/http/CHANGELOG.md
@@ -1,3 +1,7 @@
+## 1.6.1-wip
+
+* Clarified the behavior of response headers in API documentation comments.
+
 ## 1.6.0
 
 * **Breaking** Change the behavior of `Request.body` so that a charset
diff --git a/pkgs/http/lib/src/base_response.dart b/pkgs/http/lib/src/base_response.dart
index 72415dbc5c..507f521ac3 100644
--- a/pkgs/http/lib/src/base_response.dart
+++ b/pkgs/http/lib/src/base_response.dart
@@ -32,22 +32,26 @@ abstract class BaseResponse {
   /// The HTTP headers returned by the server.
   ///
   /// The header names are converted to lowercase and stored with their
-  /// associated header values.
+  /// associated header values. Because header names are lower-cased, you should
+  /// always use lowercase keys to access them (e.g.,
+  /// `response.headers['content-type']`).
   ///
   /// If the server returns multiple headers with the same name then the header
-  /// values will be associated with a single key and seperated by commas and
+  /// values will be associated with a single key and separated by commas and
   /// possibly whitespace. For example:
   /// ```dart
   /// // HTTP/1.1 200 OK
   /// // Fruit: Apple
   /// // Fruit: Banana
   /// // Fruit: Grape
-  /// final values = response.headers['fruit']!.split(RegExp(r'\s*,\s*'));
-  /// // values = ['Apple', 'Banana', 'Grape']
+  /// final values = response.headers['fruit']!;
+  /// // values = 'Apple, Banana, Grape'
   /// ```
   ///
   /// To retrieve the header values as a `List<String>`, use
-  /// [HeadersWithSplitValues.headersSplitValues].
+  /// [HeadersWithSplitValues.headersSplitValues]. This is particularly
+  /// important for the `Set-Cookie` header, as the values may contain commas
+  /// that make manual splitting difficult.
   ///
   /// If a header value contains whitespace then that whitespace may be replaced
   /// by a single space. Leading and trailing whitespace in header values are
@@ -55,7 +59,11 @@ abstract class BaseResponse {
   ///
   /// Some headers may be excluded by the [Client] for security or privacy
   /// reasons. For example, browser-based clients can only return headers in the
-  /// CORS safelist or specifically allowed by the server.
+  /// CORS safelist or specifically allowed by the server. The server can
+  /// control which headers are exposed to clients running in the browser by
+  /// setting the
+  /// [`Access-Control-Expose-Headers`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Expose-Headers)
+  /// header.
   final Map<String, String> headers;
 
   final bool isRedirect;
diff --git a/pkgs/http/pubspec.yaml b/pkgs/http/pubspec.yaml
index 66598d1f48..b140067b54 100644
--- a/pkgs/http/pubspec.yaml
+++ b/pkgs/http/pubspec.yaml
@@ -1,5 +1,5 @@
 name: http
-version: 1.6.0
+version: 1.6.1-wip
 description: A composable, multi-platform, Future-based API for HTTP requests.
 repository: https://github.com/dart-lang/http/tree/master/pkgs/http