Re-alphabetize underscored attributes reference (#60558)

Author: xwu

docs/ReferenceGuides/UnderscoredAttributes.md

@@ -23,6 +23,10 @@ the Swift ABI. This attribute is intended for the SIMD types in the standard
 library which use it to increase the alignment of their internal storage to at
 least 16 bytes.
 
+## `@_alwaysEmitConformanceMetadata`
+
+Forces conformances of the attributed protocol to always have their Type Metadata get emitted into the binary and prevents it from being optimized away or stripped by the linker.
+
 ## `@_alwaysEmitIntoClient`
 
 Forces the body of a function to be emitted into client code.
@@ -39,6 +43,14 @@ Most notably, default argument expressions are implicitly
 `@_alwaysEmitIntoClient`, which means that adding a default argument to a
 function which did not have one previously does not break ABI.
 
+## `@_assemblyVision`
+
+Forces emission of assembly vision remarks for a function or method, showing
+where various runtime calls and performance impacting hazards are in the code
+at source level after optimization.
+
+Adding this attribute to a type leads to remarks being emitted for all methods.
+
 ## `@_backDeploy(before: ...)`
 
 Causes the body of a function to be emitted into the module interface to be
@@ -53,14 +65,6 @@ client is called instead.
 For more details, see the [pitch thread](https://forums.swift.org/t/pitch-function-back-deployment/55769/)
 in the forums.
 
-## `@_assemblyVision`
-
-Forces emission of assembly vision remarks for a function or method, showing
-where various runtime calls and performance impacting hazards are in the code
-at source level after optimization.
-
-Adding this attribute to a type leads to remarks being emitted for all methods.
-
 ## `@_borrowed`
 
 Indicates that the [conservative access pattern](/docs/Lexicon.md#access-pattern)
@@ -482,6 +486,19 @@ Fun fact: Rust has a very similar concept called
 including one called `Send`,
 which inspired the design of `Sendable`.
 
+## `@_noAllocation`, `@_noLocks`
+
+These attributes are performance annotations. If a function is annotated with
+such an attribute, the compiler issues a diagnostic message if the function
+calls a runtime function which allocates memory or locks, respectively.
+The `@_noLocks` attribute implies `@_noAllocation` because a memory allocation
+also locks.
+
+## `@_noImplicitCopy`
+
+Marks a var decl as a variable that must be copied explicitly using the builtin
+function Builtin.copy.
+
 ## `@_nonEphemeral`
 
 Marks a function parameter that cannot accept a temporary pointer produced from
@@ -755,6 +772,14 @@ Clients can access SPI by marking the import as `@_spi(spiName) import Module`.
 This design makes it easy to find out which clients are using certain SPIs by
 doing a textual search.
 
+## `@_spi_available(platform, version)`
+
+Like `@available`, this attribute indicates a decl is available only as an SPI.
+This implies several behavioral changes comparing to regular `@available`:
+1. Type checker diagnoses when a client accidently exposes such a symbol in library APIs.
+2. When emitting public interfaces, `@_spi_available` is printed as `@available(platform, unavailable)`.
+3. ClangImporter imports ObjC macros `SPI_AVAILABLE` and `__SPI_AVAILABLE` to this attribute.
+
 ## `@_staticInitializeObjCMetadata`
 
 Indicates that a static initializer should be emitted to register the
@@ -789,19 +814,11 @@ A type eraser has the following restrictions:
 This feature was designed to be used for compiler-driven type erasure for
 dynamic replacement of functions with an opaque return type.
 
-## `@_weakLinked`
-
-Allows a declaration to be weakly-referenced, i.e., any references emitted by
-client modules to the declaration's symbol will have weak linkage. This means
-that client code will compile without the guarantee that the symbol will be
-available at runtime. This requires a dynamic safety check (such as using
-`dlsym (3)`); otherwise, accessing the symbol when it is unavailable leads
-to a runtime crash.
+## `@_unavailableFromAsync`
 
-This is an unsafe alternative to using `@available`, which is statically checked.
-If the availability of a library symbol is newer than the deployment target of
-the client, the symbol will be weakly linked, but checking for `@available` and
-`#(un)available` ensures that a symbol is not accessed when it is unavailable.
+Marks a synchronous API as being unavailable from asynchronous contexts. Direct
+usage of annotated API from asynchronous contexts will result in a warning from
+the compiler.
 
 ## `@_unsafeMainActor`, `@_unsafeSendable`
 
@@ -812,38 +829,23 @@ within Swift 5 code that has adopted concurrency, but non-`@MainActor`
 See the forum post on [Concurrency in Swift 5 and 6](https://forums.swift.org/t/concurrency-in-swift-5-and-6/49337)
 for more details.
 
-## `@_noImplicitCopy`
-
-Marks a var decl as a variable that must be copied explicitly using the builtin
-function Builtin.copy.
-
-## `@_noAllocation`, `@_noLocks`
-
-These attributes are performance annotations. If a function is annotated with
-such an attribute, the compiler issues a diagnostic message if the function
-calls a runtime function which allocates memory or locks, respectively.
-The `@_noLocks` attribute implies `@_noAllocation` because a memory allocation
-also locks.
-
-## `@_unavailableFromAsync`
-
-Marks a synchronous API as being unavailable from asynchronous contexts. Direct
-usage of annotated API from asynchronous contexts will result in a warning from
-the compiler.
-
 ## `@_unsafeInheritExecutor`
 
 This `async` function uses the pre-SE-0338 semantics of unsafely inheriting the caller's executor.  This is an underscored feature because the right way of inheriting an executor is to pass in the required executor and switch to it.  Unfortunately, there are functions in the standard library which need to inherit their caller's executor but cannot change their ABI because they were not defined as `@_alwaysEmitIntoClient` in the initial release.
 
+## `@_weakLinked`
 
-## `@_spi_available(platform, version)`
-
-Like `@available`, this attribute indicates a decl is available only as an SPI.
-This implies several behavioral changes comparing to regular `@available`:
-1. Type checker diagnoses when a client accidently exposes such a symbol in library APIs.
-2. When emitting public interfaces, `@_spi_available` is printed as `@available(platform, unavailable)`.
-3. ClangImporter imports ObjC macros `SPI_AVAILABLE` and `__SPI_AVAILABLE` to this attribute.
+Allows a declaration to be weakly-referenced, i.e., any references emitted by
+client modules to the declaration's symbol will have weak linkage. This means
+that client code will compile without the guarantee that the symbol will be
+available at runtime. This requires a dynamic safety check (such as using
+`dlsym (3)`); otherwise, accessing the symbol when it is unavailable leads
+to a runtime crash.
 
+This is an unsafe alternative to using `@available`, which is statically checked.
+If the availability of a library symbol is newer than the deployment target of
+the client, the symbol will be weakly linked, but checking for `@available` and
+`#(un)available` ensures that a symbol is not accessed when it is unavailable.
 
 ## `_local`
 
@@ -852,8 +854,3 @@ the distributed actor isolation checks. This is used for things like `whenLocal`
 where the actor passed to the closure is known-to-be-local, and similarly a 
 `self` of obtained from an _isolated_ function inside a distributed actor is 
 also guaranteed to be local by construction.
-
-
-## `@_alwaysEmitConformanceMetadata`
-
-Forces conformances of the attributed protocol to always have their Type Metadata get emitted into the binary and prevents it from being optimized away or stripped by the linker.