From 5b89338a35c6406f5af976017756e361f91ea9e2 Mon Sep 17 00:00:00 2001
From: Anne van Kesteren <annevk@annevk.nl>
Date: Thu, 19 Apr 2018 16:25:32 +0200
Subject: [PATCH] Clarify how Headers does not support Set-Cookie

Fixes #345.
---
 fetch.bs | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/fetch.bs b/fetch.bs
index 106e51343..b9d957de4 100644
--- a/fetch.bs
+++ b/fetch.bs
@@ -4384,9 +4384,16 @@ interface Headers {
   iterable&lt;ByteString, ByteString>;
 };</pre>
 
+<p class=note>Unlike a <a>header list</a>, a {{Headers}} object cannot represent more than one
+`<code>Set-Cookie</code>` <a for=/>header</a>. In a way this is problematic as unlike all other
+headers `<code>Set-Cookie</code>` headers cannot be combined, but since `<code>Set-Cookie</code>`
+headers are not exposed to client-side JavaScript this is deemed an acceptable compromise.
+Implementations could chose the more efficient {{Headers}} object representation even for a
+<a>header list</a>, as long as they also support an associated data structure for
+`<code>Set-Cookie</code>` headers.
+
 <div class=example id=example-headers-class>
- <p>Constructing a {{Headers}} object from scratch is fairly straightforward. You could pass in a
- JavaScript object representing a header hash map, or an array of ordered pairs:
+ <p>A {{Headers}} object can be initialized with various JavaScript data structures:
 
  <pre>
 var meta = { "Content-Type": "text/xml", "Breaking-Bad": "&lt;3" }