Add appendix on using newtypes/type tags

Signed-off-by: Nick Cameron <[email protected]>

Author: nrc

text/0000-dyno.md

@@ -61,7 +61,8 @@ fn report_error(e: &dyn Error) {
     }
 
     // Help text suggestion.
-    // Note, we should use a newtype here to prevent confusing different string context information.
+    // Note, we should use explicit tags or a newtype here to prevent confusing different string
+    // context information (see appendix).
     if let Some(suggestion) = e.get_context_ref::<str>() {
         emit_suggestion(suggestion);
     }
@@ -288,7 +289,33 @@ Extending the API of `Error` is a primary motivation for this RFC, but those ext
 
 It was suggested by @Plecra in the [comments](https://github.com/rust-lang/rfcs/pull/2895#issuecomment-735713486) of RFC 2895, that this mechanism could be used for providing data from a future's `Context` object. That is a more demanding application since it is likely to require `&mut` references, objects with complex lifetimes, and possibly even closures to be returned. That has motivated seeking a general API for `provide_any`, rather than only supporting `'static` lifetimes.
 
+Recommendations for how to use the API, in particular when to provide or request a value using a plain type, type tag, or special purpose newtype. See the appendix for discussion and examples.
+
 # Future possibilities
 [future-possibilities]: #future-possibilities
 
 A possible extension to this work is full downcasting using type tags - a proper alternative to `Any`. Such downcasting is available in dyno and is an implementation detail of the proof of concept implementation for this RFC. It is not part of `provide_any`'s interface in order to minimise the proposal and avoid overlap with `Any`, however, I don't see any technical issues with exposing such functionality in the future if there is demand.
+
+# Appendix: using tags or newtypes
+
+One issue with using type-based provision is that an object might reasonably provide many different values with the same type. If the object intends to provide multiple values with the same type, then it must distinguish them. Even if it doesn't, the user might request a value expecting one thing and get another with the same type, leading to logic errors (e.g., requesting a string from `MyError` expecting an error code and getting a suggestion message).
+
+There are two possible solutions (both of these use the API as proposed, neither requires extensions): wrap values in value-specific newtypes, or use value-specific type tags.
+
+I'll explain these options in the context of the `MyError` example.
+
+Using newtypes, the `MyError` author would provide a `Suggestion` newtype: `pub struct Suggestion(pub String)`. A user would use `get_context::<Suggestion>()` (or otherwise specify the type, e.g., `let s: Suggestion = e.get_context().unwrap();`) and would receive a `Suggestion` which they would then have to unpack to retrieve the string value. This approach only works for owned `String`s: newtypes cannot wrap unsized values, and keeping a reference in the newtype would require using an explicit tag, making the newtype option strictly worse than the type tag option.
+
+Using type tags, the `MyError` author would provide a `SuggestionTag` type tag:
+
+```rust
+pub struct SuggestionTag;
+
+impl<'a> TypeTag<'a> for SuggestionTag {
+    type Type = &'a str;
+}
+```
+
+The user would use `get_context_by_type_tag::<SuggestionTag>` to retrieve the suggestion. This approach supports references, so the suggestion message does not need to be cloned, and returns the string directly to the user without them having to unpack a newtype. However, it does require the user to understand the type tag concept.
+
+Note that the type tags option relies on their being a potential many-to-one relationship between type tags and types.