SE-0498: clarify state of output span after truncated demangle (#3051)

Author: ktoso

proposals/0498-runtime-demangle.md

@@ -55,9 +55,9 @@ The span accepting API is necessary for performance sensitive use-cases, which a
 
 The output from this API is an `OutputSpan` of `UTF8.CodeUnit`s, and it may not necessarily be well-formed UTF8, because of the potential of truncation happening between two code units which would render the UTF8 invalid.
 
-If the demangled representation does not fit the preallocated buffer, the demangle method will return `truncated(actualSize)` such that developers can determine by how much the buffer might need to be increased to handle the complete demangling.
+If the demangled representation does not fit the preallocated buffer, the demangle method will return `truncated(actualSize)` such that developers can determine by how much the buffer might need to be increased to handle the complete demangling. When `.truncated` is returned, the `OutputSpan` will contain a _partial result_, of however many characters were able to fit into it before truncation ocurred. This also means that a truncated output may not be entirely valid UTF8. 
 
-To construct an `UTF8Span` or valid `String` from the `OutputSpan` you can do the following:
+Converting the outputSpan to a `String`, which is guarateed to be valid UTF8, follows the below pattern, where creating an `UTF8Span` _will_ perform validation of the UTF8 String contents, and fail if the output wasn't correct. 
 
 ```swift
 var demangledOutputSpan: OutputSpan<UTF8.CodeUnit> = ...
@@ -69,6 +69,8 @@ if demangle("$sSG", into: &demangledOutputSpan) == .success {
 }
 ```
 
+As this example shows, the path to constructing a String is therefore safe, and we don't want to perform validation earlier during `demangle`, because you may want to store the exact bytes that were returned for some future processing.
+
 ### Demangling format
 
 While the mangled strings are part of Swift ABI and can therefore not really change on platforms with stable ABI, the demangled representation returned by the `demangle` functions is _not guaranteed to be stable in any way_.