Rollup merge of #124514 - michaelwoerister:zero-disambiguator-demangl…

…ing-recommendation, r=davidtwco

Recommend to never display zero disambiguators when demangling v0 symbols

This PR extends the [v0 symbol mangling documentation](https://doc.rust-lang.org/rustc/symbol-mangling/v0.html) with the strong recommendation that demanglers should never display zero-disambiguators, especially when dealing with `crate-root`.

Being able to rely on `C3foo` to be rendered as `foo` (i.e. without explicit disambiguator value) rather than as `foo[0]` allows the compiler to encode things like new basic types in a backward compatible way. This idea has been originally proposed by `@eddyb` in [the discussion around supporting `f16` and `f128` in the v0 mangling scheme](#122106). It is a generally useful mechanism for supporting a certain class of new elements in the v0 mangling scheme in a backward compatible way (whether as a temporary workaround until downstream tooling has picked up grammar changes or as a permanent encoding).

cc `@tgross35`

src/doc/rustc/src/symbol-mangling/v0.md

@@ -150,6 +150,15 @@ the *[disambiguator]* is used to make the name unique across the crate graph.
 > ```
 >
 > Recommended demangling: `mycrate::example`
+>
+> Note: The compiler may re-use the *crate-root* form to express arbitrary
+> unscoped, undisambiguated identifiers, such as for new basic types that have
+> not been added to the grammar yet. To achieve that, it will emit a *crate-root*
+> without an explicit disambiguator, relying on the fact that such an
+> undisambiguated crate name cannot occur in practice. For example, the basic
+> type `f128` would be encode as `C4f128`. For this to have the desired effect,
+> demanglers are expected to never render zero disambiguators of crate roots.
+> I.e. `C4f128` is expected to be displayed as `f128` and not `f128[0]`.
 
 ### Path: Inherent impl
 [inherent-impl]: #path-inherent-impl
@@ -539,6 +548,10 @@ This allows disambiguators that are encoded sequentially to use minimal bytes.
 > **Recommended Demangling**
 >
 > The *disambiguator* may or may not be displayed; see recommendations for rules that use *disambiguator*.
+> Generally, it is recommended that zero disambiguators are never displayed unless their accompanying
+> identifier is empty (like is the case for unnamed items such as closures).
+> When rendering a disambiguator, it can be shortened to a length reasonable for the context,
+> similar to how git commit hashes are rarely displayed in full.
 
 ## Lifetime
 [lifetime]: #lifetime