Add more syscall doc aliases to std docs by SabrinaJewson · Pull Request #113891 · rust-lang/rust (original) (raw)

A couple of thoughts:

• Putting aliases from many different platforms (e.g., Windows and Linux and WASI and ...) into the same search context feels like it may not be a good idea. Unfortunately we don't make it easy to pick the platform, but it would seem unfortunate to me to pollute the search namespace with a bunch of different names. It's also much more likely to run into collisions (e.g., a single name doing two different things on different platforms).
• The cases where the alias being added already starts with the same name (e.g., Create* and a Rust function create_...) seems to carry less value to me. If someone copy/pastes or writes the full name before looking at search results, it might be helpful, but it feels like the alias feature isn't a great fit for that interaction pattern. It might make more sense to include the aliases in such a case into the regular doc comments on the relevant functions, so that hopefully a full-text search engine (e.g., Google) can better index the contents.

My sense is that aliases are most helpful where the libc name and concept are somewhat obscure (e.g., popcnt) and it's not clear what the name Rust would choose is. Where the name or location of that concept in the standard library are much clearer, I think the value significantly diminishes. For example, ~all of the aliases on Instant and SystemTime proposed here feel excessive to me: if I'm looking for time, I can already get very good results with time in the search bar.

I'm not sure what the best way to get this reviewed is. @SabrinaJewson, are you still interested in pushing this forward? Perhaps we can split out the non-controversial bits and get those landed first, and then solicit more opinions from the library team on what folks think here?