You should document (or link documentation for) your list of supported ABIs

I am reading the Rust reference. In section 6.4 it notes a function may be augmented with an extern "something" prefix to make it use the "something" function ABI. It mentions "Rust", "C", and "stdcall" as examples. However, it does not list what ABIs are allowed.

I do not expect the Rust reference to document all of the allowed ABIs, because the Rust reference says in the introduction "this book does not usually document the specifics of rustc as a tool... rustc has its own book". I would expect the list of allowed extern ABIs to be an implementation detail of the compiler, rustc or otherwise, and probably not appropriate for the reference (unless those ABIs are a required feature of all compliant Rust compilers). However, if I go to the rustc book and search, using the magnifying glass icon at the top, for "abi" I do not find anything like a list of supported ABIs.

I asked for help finding an ABI list on "Twitter". I got two responses of places I should look, which I found unsatisfying:

• A couple people linked this abi.rs file in the Rust source. This source is semi-obviously not adequate documentation even if someone knows how to find it, in particular the big enum at the top differs in things like capitalization from how the "abi" strings are formatted.
• It turns out within the reference there is another section, 6.13, on external blocks, which does have a list of allowed ABI strings. However there are three problems with this section: One, although 6.4 incidentally links 6.13 it does not indicate 6.13 contains the ABI list, which would make this list hard to find if one is reading the reference guide linearly (or nonlinearly but happening to read 6.4 before 6.13); two, the list in 6.13 does not indicate which platforms each of the ABIs is available on (for example it notes "stdcall" is the default for the "system" alias on x86_32 Windows, but doesn't indicate whether it is allowed on x86_64); and three, as the person on Twitter who helped me find this list pointed out, it doesn't list ABIs which are currently allowed but unstable.

My "Expected Behavior" is:

• There should be, somewhere in the world, a document listing all the ABI strings which are allowed in a function extern or block extern {} in official rustc. The list should indicate for each string which platforms it is currently available on. If a string is unstable or may be removed in future, it should be listed, but marked as unstable. In my personal opinion the most sensible place for this list to be would be in the rustc book.
• If the list is somewhere in the world other than the rustc book (which the reference manual calls out early as containing additional information), rustc reference section 6.4 "functions" should link that list (or 6.13 should link it and 6.4 should link 6.13).
• If section 6.13 is going to contain normative text that changes the interpretation of 6.4 (which it currently does: "there are three ABI strings which are cross-platform, and which all compilers are guaranteed to support"), then 6.4 should contain a link to 6.13 explicitly labeled with "more information on supported ABI strings is in section 6.13" (or something).

IMO

Start with the Rust Reference sections 6.4 and 6.13, the rustc book, and compiler/rustc_target/src/spec/abi.rs. Determine where the authoritative ABI list belongs, how platform availability and unstable ABIs should be represented, and how the Reference should link to it. Done means the official documentation lists supported ABI strings with their platform and stability information and provides the requested cross-links.