Tweak a few fields docs (#99)

* Tweak a few `fields` docs

- This patch clarifies the behavior of the various `fields` methods when syntactically invalid
  inputs are given. Some methods already noted this, but `get` in particular was missing a
  clarification that an invalid key would result in an empty list result

- Removed some text in the doc for `from-list`. While non-UTF-8 values are not preferred for new
  applications, they are syntactically valid due to the [`obs-text`
  production](https://www.rfc-editor.org/rfc/rfc9110#section-5.5-2) in the RFC grammar.

* regenerate markdown

Author: acfoltzer

proxy.md

@@ -745,11 +745,9 @@ http-related errors.</p>
 which have multiple values are represented by multiple entries in this
 list with the same key.</p>
 <p>The tuple is a pair of the field key, represented as a string, and
-Value, represented as a list of bytes. In a valid Fields, all keys
-and values are valid UTF-8 strings. However, values are not always
-well-formed, so they are represented as a raw list of bytes.</p>
-<p>An error result will be returned if any header or value was
-syntactically invalid, or if a header was forbidden.</p>
+Value, represented as a list of bytes.</p>
+<p>An error result will be returned if any <a href="#field_key"><code>field-key</code></a> or <a href="#field_value"><code>field-value</code></a> is
+syntactically invalid, or if a field is forbidden.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="static_fields.from_list.entries"></a><code>entries</code>: list&lt;(<a href="#field_key"><a href="#field_key"><code>field-key</code></a></a>, <a href="#field_value"><a href="#field_value"><code>field-value</code></a></a>)&gt;</li>
@@ -760,9 +758,9 @@ syntactically invalid, or if a header was forbidden.</p>
 </ul>
 <h4><a name="method_fields.get"></a><code>[method]fields.get: func</code></h4>
 <p>Get all of the values corresponding to a key. If the key is not present
-in this <a href="#fields"><code>fields</code></a>, an empty list is returned. However, if the key is
-present but empty, this is represented by a list with one or more
-empty field-values present.</p>
+in this <a href="#fields"><code>fields</code></a> or is syntactically invalid, an empty list is returned.
+However, if the key is present but empty, this is represented by a list
+with one or more empty field-values present.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="method_fields.get.self"></a><code>self</code>: borrow&lt;<a href="#fields"><a href="#fields"><code>fields</code></a></a>&gt;</li>
@@ -788,6 +786,8 @@ syntactically invalid, <code>false</code> is returned.</p>
 <p>Set all of the values for a key. Clears any existing values for that
 key, if they have been set.</p>
 <p>Fails with <code>header-error.immutable</code> if the <a href="#fields"><code>fields</code></a> are immutable.</p>
+<p>Fails with <code>header-error.invalid-syntax</code> if the <a href="#field_key"><code>field-key</code></a> or any of
+the <a href="#field_value"><code>field-value</code></a>s are syntactically invalid.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="method_fields.set.self"></a><code>self</code>: borrow&lt;<a href="#fields"><a href="#fields"><code>fields</code></a></a>&gt;</li>
@@ -802,6 +802,8 @@ key, if they have been set.</p>
 <p>Delete all values for a key. Does nothing if no values for the key
 exist.</p>
 <p>Fails with <code>header-error.immutable</code> if the <a href="#fields"><code>fields</code></a> are immutable.</p>
+<p>Fails with <code>header-error.invalid-syntax</code> if the <a href="#field_key"><code>field-key</code></a> is
+syntactically invalid.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="method_fields.delete.self"></a><code>self</code>: borrow&lt;<a href="#fields"><a href="#fields"><code>fields</code></a></a>&gt;</li>
@@ -815,6 +817,8 @@ exist.</p>
 <p>Append a value for a key. Does not change or delete any existing
 values for that key.</p>
 <p>Fails with <code>header-error.immutable</code> if the <a href="#fields"><code>fields</code></a> are immutable.</p>
+<p>Fails with <code>header-error.invalid-syntax</code> if the <a href="#field_key"><code>field-key</code></a> or
+<a href="#field_value"><code>field-value</code></a> are syntactically invalid.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="method_fields.append.self"></a><code>self</code>: borrow&lt;<a href="#fields"><a href="#fields"><code>fields</code></a></a>&gt;</li>

wit/types.wit

@@ -159,20 +159,18 @@ interface types {
     /// list with the same key.
     ///
     /// The tuple is a pair of the field key, represented as a string, and
-    /// Value, represented as a list of bytes. In a valid Fields, all keys
-    /// and values are valid UTF-8 strings. However, values are not always
-    /// well-formed, so they are represented as a raw list of bytes.
+    /// Value, represented as a list of bytes.
     ///
-    /// An error result will be returned if any header or value was
-    /// syntactically invalid, or if a header was forbidden.
+    /// An error result will be returned if any `field-key` or `field-value` is
+    /// syntactically invalid, or if a field is forbidden.
     from-list: static func(
       entries: list<tuple<field-key,field-value>>
     ) -> result<fields, header-error>;
 
     /// Get all of the values corresponding to a key. If the key is not present
-    /// in this `fields`, an empty list is returned. However, if the key is
-    /// present but empty, this is represented by a list with one or more
-    /// empty field-values present.
+    /// in this `fields` or is syntactically invalid, an empty list is returned.
+    /// However, if the key is present but empty, this is represented by a list
+    /// with one or more empty field-values present.
     get: func(name: field-key) -> list<field-value>;
 
     /// Returns `true` when the key is present in this `fields`. If the key is
@@ -183,18 +181,27 @@ interface types {
     /// key, if they have been set.
     ///
     /// Fails with `header-error.immutable` if the `fields` are immutable.
+    ///
+    /// Fails with `header-error.invalid-syntax` if the `field-key` or any of
+    /// the `field-value`s are syntactically invalid.
     set: func(name: field-key, value: list<field-value>) -> result<_, header-error>;
 
     /// Delete all values for a key. Does nothing if no values for the key
     /// exist.
     ///
     /// Fails with `header-error.immutable` if the `fields` are immutable.
+    ///
+    /// Fails with `header-error.invalid-syntax` if the `field-key` is
+    /// syntactically invalid.
     delete: func(name: field-key) -> result<_, header-error>;
 
     /// Append a value for a key. Does not change or delete any existing
     /// values for that key.
     ///
     /// Fails with `header-error.immutable` if the `fields` are immutable.
+    ///
+    /// Fails with `header-error.invalid-syntax` if the `field-key` or
+    /// `field-value` are syntactically invalid.
     append: func(name: field-key, value: field-value) -> result<_, header-error>;
 
     /// Retrieve the full set of keys and values in the Fields. Like the