SE-0047 has been accepted:
I suggest implementing this as a series of independent patches:
1) Introduce the @discardableResult declaration attribute.
2) Change the standard library to use it on various mutating methods that return values.
3) Change the clang importer to auto-attach the attribute to imported declarations (ones that are not marked with the clang "_attribute_((warn_unused_result))").
4) Parse and recognize the new doc comments (mutableVariant, etc.). See comment from Chris Lattner below.
5) Change the compiler to start listening to the @discardableResult attribute.
6) Change the @warn_unused_result attribute to be recognized, and produce an error + fixit to remove it.