Adopt @abi in the standard library

docs/ReferenceGuides/UnderscoredAttributes.md

@@ -1131,15 +1131,17 @@ ways to misuse it:
   be reliably recovered through C interfaces like `dlsym`. If you want to
   implement a plugin-style interface, use `Bundle`/`NSBundle` if available, or
   export your plugin entry points as C entry points using `@_cdecl`.
-
+- Don't use `@_silgen_name` when you need to make a change to an ABI-stable
+  declaration's signature that would normally alter its mangled name, but you
+  need to preserve the old mangled name for ABI compatibility. We used to use it
+  for this task, but `@abi` can do it with fewer limitations, more safety, and
+  better readability. If for some reason you do need `@_silgen_name`, you will
+  need to be careful that the change doesn't materially affect the actual
+  calling convention of the function in an incompatible way.
+
 Legitimate uses may include:
 
 - Use `@_silgen_name` if you're implementing the Swift runtime.
-- Use `@_silgen_name` if you need to make a change to an ABI-stable
-  declaration's signature that would normally alter its mangled name, but you
-  need to preserve the old mangled name for ABI compatibility. You will need
-  to be careful that the change doesn't materially affect the actual calling
-  convention of the function in an incompatible way.
 - Use `@_silgen_name` if certain declarations need to have predictable symbol
   names, such as to be easily referenced by linker scripts or other highly
   customized build environments (and it's OK for those predictable symbols to

docs/StandardLibraryProgrammersManual.md

@@ -455,6 +455,8 @@ This attribute specifies the name that a declaration will have at link time. It
 1. To specify the symbol name of a Swift function so that it can be called from Swift-aware C. Such functions have bodies.
 2. To provide a Swift declaration which really represents a C declaration. Such functions do not have bodies.
 
+In the past it was sometimes used for ABI backwards compatibility hacks, but `@abi` does this job better.
+
 ##### Using `@_silgen_name` to call Swift from Swift-aware C
 
 Rather than hard-code Swift mangling into C code, `@_silgen_name` is used to provide a stable and known symbol name for linking. Note that C code still must understand and use the Swift calling convention (available in swift-clang) for such Swift functions (if they use Swift's CC). Example: