Tweak a few fields docs
#99
Conversation
- 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.
There was a problem hiding this comment.
This looks right to me, nice spots!
Separately, and of interest to the WASI Subgroup process for post-0.2.0 evolution, we should discuss how these changes get published. My inclination is that, since the changes are essentially editorial, this is still part of 0.2.0 so maybe we just update the WASI Preview 2 snapshot in-place? (cc @pchickey @sunfishcode @ricochet )
| /// 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. |
There was a problem hiding this comment.
This seems like the right choice given that 0.2.0 is frozen and we can't change the types. But the next time we can make a breaking change (e.g., 0.3.0), I wonder if a syntactically-invalid key parameter should produce an error and thus the return value should be wrapped in a result? The answer doesn't affect this PR, but separately we could start a list of "pending tweaks for 0.3.0" if we agree.
There was a problem hiding this comment.
I think that would be more consistent with the other methods, and would support carrying it forward as a proposed change for 0.3.0.
|
With regard to pushing docs improvements up to the snapshot in the root WebAssembly/WASI repo - lets make sure that whatever editorial changes are discussed in the proposals themselves, and then I can mechanically update the version we "publish" there as needed. |
This patch clarifies the behavior of the various
fieldsmethods when syntactically invalid inputs are given. Some methods already noted this, butgetin particular was missing a clarification that an invalid key would result in an empty list resultRemoved 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 theobs-textproduction in the RFC grammar.