doc(alias): should it be a mapping rather than search terms?

[ojeda]

PRs such as #81988 and #81989 add aliases inspired in terms coming from other languages such as C, Python and Java.

Questions were raised about how far are we willing to go: should we really add a mapping of functions/features from other languages to Rust? Where do we stop? i.e. "how much is too much".

If the changes in those two PRs are agreed to be useful, then I think we should consider making the mapping "official" and elevate it to that, rather than just a bunch of related search terms without documentation. In other words, something like:

#[doc(alias = "sprintf", lang = "C, C++, POSIX")]

This would bring a series of advantages:

• Documentation: easier to tell where the alias comes from and maintain it. Answers things like: "why is this alias here?", "did it come from C, C++, POSIX, Java, Python...?".
• Docs could automatically generate a page per language containing an index of terms that are mapped to Rust for newcomers from each language. It could be very useful to read for those coming from another language and getting up to speed quickly.
• Docs could show the aliases in the documentation somehow (probably opt-in).
• Docs could provide the option to disable matching terms from other languages. This is useful if aliases keep coming in: if someone is already proficient in Rust, they may only want to match aliases related to Rust, rather than "external aliases" coming from other languages. This would make the alias functionality more useful for within-Rust terms, too.
• Search could show a small "capsule tag" (e.g. with the "C" or "Python" text) when looking for a term if it matched due to an alias (unless there is a Rust one exactly).
• Other tools could also use this mapping.

The downside, of course, is that there could be a lot of this lines added and clutter the source code if many people start adding terms from many languages. One could argue that if that happens it is because the feature became very popular (and Rust too) -- so "death by success". :) One could also argue to move it out of line.

Answering this question, whether positively or negatively, also resolves other questions that were raised such as:

• Should there be aliases that match exactly the Rust one? e.g. HashMap from Java.
• Should aliases be case-sensitive? i.e. if it is an actual mapping, it would be useful to have both NULL (for C) and null (for, say, JavaScript).
• Should aliases be added if the search already matches them? e.g. searching for both bool and _Bool already pulls up bool.

P.S. this may need to be moved to internals or written as an RFC.

[jyn514]

I think this would good as an internals thread and eventually an RFC. These all sounds nice but I would like to hear some feedback from the community about people will actually use this outside the standard library.

[steveklabnik]

Yes, IMHO this should be one of those two things. Additionally, some of this is libs team work, some of this is rustdoc team work.

[GuillaumeGomez]

One important thing to note is that the aliases are only displayed in the results if they match exactly the search query. Also, I'm not sure we should go any further on this feature. Why does it matter if the function comes from java or C++? You found it in the end with an exact match, and you'll only see the rust item which was aliased.

[ojeda]

Also, I'm not sure we should go any further on this feature.

This suggestion depends on the result of the other mentioned PRs, and given it seems we don't want to add many aliases, this can probably be closed.

Why does it matter if the function comes from java or C++?

A few advantages of having the information are explained above; but the original point was to document why a given alias is there since we were adding aliases for external languages. That additionally brings up another point: terms can greatly differ in meaning for different contexts/languages/people, e.g. "map", "string", "vector", "array", "table"...

[ojeda]

This suggestion depends on the result of the other mentioned PRs, and given it seems we don't want to add many aliases, this can probably be closed.

Those PRs were indeed closed in the end, and I am not aware of other work related to that, so let's close this.