I sometimes want to include compilation-failing code examples in API documentation to motivate features to a given approach. Using a rust,compile_fail code block header gets met half of what I want: the code is displayed with an indicator to the reader that it fails to compile.
The missing piece is that it does not include the error message. In these cases where I want to motivate solutions to the given code, I often want the reader to see the compiler error, because rustc error messages are very informative!
So I often end up copying the failing example into the main code, running cargo build to generate an error, then cutting and pasting that error into a text code block in the documentation.
If this could be automated, it would help with this pedagogical technique.
One challenge is that error cases and descriptions may be sensitive to rustc versions.
Does anyone else use this kind of technique?
The latest example that prompted this post is that I have a trait with method names colliding with Iterator and also a blanket impl of my trait for any Iterator type. So in some cases this causes method resolution ambiguity. The universal solution is to use method name disambiguation, but in my project I'm providing a convenient short-hand to resolve these specific cases.
So I want an example of an ambiguous call site, and I want to display the error to the doc reader, which explains the ambiguity and the two distinct trait methods it could refer to.