Lifetime diagnostics: clarify @_lifetime usage for inout parameters

This comes up often when passing a MutableSpan as an 'inout' argument.  The
vague diagnostic was causing developers to attempt incorrect @_lifetime
annotations. Be clear about why the annotation is needed and which annotation
should be used.

Author: atrick

include/swift/AST/DiagnosticsSema.def

@@ -8340,7 +8340,7 @@ ERROR(lifetime_dependence_feature_required_return, none,
 ERROR(lifetime_dependence_feature_required_mutating, none,
       "%0 cannot have a ~Escapable 'self'", (StringRef))
 ERROR(lifetime_dependence_feature_required_inout, none,
-      "%0 cannot have a ~Escapable 'inout' parameter '%1'",
+      "%0 cannot have a ~Escapable 'inout' parameter '%1' in addition to other ~Escapable parameters",
       // this arg list must be compatible with
       // lifetime_dependence_cannot_infer_inout
       (StringRef, StringRef))
@@ -8374,6 +8374,9 @@ ERROR(lifetime_dependence_cannot_infer_kind, none,
 ERROR(lifetime_dependence_cannot_infer_scope_ownership, none,
       "cannot borrow the lifetime of '%0', which has consuming ownership on %1",
       (StringRef, StringRef))
+NOTE(lifetime_dependence_cannot_infer_inout_suggest, none,
+     "use '@_lifetime(%0: copy %0) to forward the inout dependency",
+     (StringRef))
 
 //------------------------------------------------------------------------------
 // MARK: Lifetime Dependence Experimental Inference

lib/AST/LifetimeDependence.cpp

@@ -555,6 +555,12 @@ class LifetimeDependenceChecker {
         ctx.Diags.diagnose(param->getLoc(), diagID,
                            {StringRef(diagnosticQualifier()),
                             param->getName().str()});
+        if (diagID == diag::lifetime_dependence_cannot_infer_inout.ID) {
+          ctx.Diags.diagnose(
+            param->getLoc(),
+            diag::lifetime_dependence_cannot_infer_inout_suggest,
+            param->getName().str());
+        }
       }
     }
   }

test/Sema/lifetime_attr_nofeature.swift

@@ -8,3 +8,9 @@ struct NE : ~Escapable { // expected-error{{an implicit initializer cannot retur
 func derive(_ ne: NE) -> NE { // expected-error{{a function cannot return a ~Escapable result}}
   ne
 }
+
+func f_inout_infer(a: inout MutableRawSpan) {}
+
+func f_inout_no_infer(a: inout MutableRawSpan, b: RawSpan) {}
+// expected-error @-1{{a function cannot have a ~Escapable 'inout' parameter 'a' in addition to other ~Escapable parameters}}
+

test/Sema/lifetime_depend_infer.swift

@@ -15,6 +15,8 @@ struct NEImmortal: ~Escapable {
   init() {}
 }
 
+struct MutNE: ~Copyable & ~Escapable {}
+
 // =============================================================================
 // Handle non-Escapable results with 'self'
 // =============================================================================
@@ -577,3 +579,12 @@ struct NonEscapableMutableSelf: ~Escapable {
   @_lifetime(&self)
   mutating func mutatingMethodOneParamBorrow(_: NE) {}
 }
+
+// =============================================================================
+// Handle common mistakes with inout parameter annotations
+// =============================================================================
+
+// Unable to infer an 'inout' dependency. Provide valid guidance.
+//
+func f_inout_no_infer(a: inout MutNE, b: NE) {} // expected-error{{a function with a ~Escapable 'inout' parameter requires '@_lifetime(a: ...)'}}
+// expected-note @-1{{use '@_lifetime(a: copy a) to forward the inout dependency}}