Merge pull request #2001 from ehuss/extern-default

More clearly define the default abi of an extern block

Author: traviscross

src/glossary.md

@@ -11,6 +11,14 @@ The alignment of a value specifies what addresses values are preferred to
 start at. Always a power of two. References to a value must be aligned.
 [More][alignment].
 
+r[glossary.abi]
+### Application binary interface (ABI)
+
+An *application binary interface* (ABI) defines how compiled code interacts with other compiled code. With [`extern` blocks] and [`extern fn`], *ABI strings* affect:
+
+- **Calling convention**: How function arguments are passed, values are returned (e.g., in registers or on the stack), and who is responsible for cleaning up the stack.
+- **Unwinding**: Whether stack unwinding is allowed. For example, the `"C-unwind"` ABI allows unwinding across the FFI boundary, while the `"C"` ABI does not.
+
 ### Arity
 
 Arity refers to the number of arguments a function or operator takes.
@@ -287,6 +295,8 @@ uninhabited type is "empty" in the sense that there are no values of the type. T
 example of an uninhabited type is the [never type] `!`, or an enum with no variants
 `enum Never { }`. Opposite of [Inhabited](#inhabited).
 
+[`extern` blocks]: items.extern
+[`extern fn`]: items.fn.extern
 [alignment]: type-layout.md#size-and-alignment
 [associated item]: #associated-item
 [attributes]: attributes.md

src/items/external-blocks.md

@@ -98,14 +98,21 @@ r[items.extern.abi]
 ## ABI
 
 r[items.extern.abi.intro]
-By default external blocks assume that the library they are calling uses the
-standard C ABI on the specific platform. Other ABIs may be specified using an
-`abi` string, as shown here:
+The `extern` keyword can be followed by an optional [ABI] string. The ABI specifies the calling convention of the functions in the block. The calling convention defines a low-level interface for functions, such as how arguments are placed in registers or on the stack, how return values are passed, and who is responsible for cleaning up the stack.
 
-```rust
-// Interface to the Windows API
-unsafe extern "system" { }
-```
+> [!EXAMPLE]
+> ```rust
+> // Interface to the Windows API.
+> unsafe extern "system" { /* ... */ }
+> ```
+
+r[items.extern.abi.default]
+If the ABI string is not specified, it defaults to `"C"`.
+
+> [!NOTE]
+> The `extern` syntax without an explicit ABI is being phased out, so it's better to always write the ABI explicitly.
+>
+> For more details, see [Rust issue #134986](https://github.com/rust-lang/rust/issues/134986).
 
 r[items.extern.abi.standard]
 The following ABI strings are supported on all platforms:
@@ -472,6 +479,7 @@ r[items.extern.attributes.fn-parameters]
 Attributes on extern function parameters follow the same rules and
 restrictions as [regular function parameters].
 
+[ABI]: glossary.abi
 [PE Format]: https://learn.microsoft.com/windows/win32/debug/pe-format#import-name-type
 [UEFI]: https://uefi.org/specifications
 [WebAssembly module]: https://webassembly.github.io/spec/core/syntax/modules.html