Add more syscall doc aliases to std docs #113891

SabrinaJewson · 2023-07-20T16:27:16Z

Some of these are quite trivial but we should optimize for the user not having to think about it.

rustbot · 2023-07-20T16:27:25Z

(rustbot has picked a reviewer for you, use r? to override)

SabrinaJewson

This PR breaks the doc alias policy in quite a few places, which I’ve now highlighted. I left them in the PR itself because I wasn’t sure what the best course of action was. (In my opinion, after making this PR, the policy is overly restrictive).

SabrinaJewson · 2023-07-20T16:36:41Z

library/std/src/fs.rs

@@ -1937,6 +1943,7 @@ pub fn metadata<P: AsRef<Path>>(path: P) -> io::Result<Metadata> {
 ///     Ok(())
 /// }
 /// ```
+#[doc(alias = "lstat", alias = "GetFileAttributes", alias = "GetFileAttributesEx")]


The Windows functions here break the doc alias policy, since GetFileAttributes is now mapped to multiple functions. We now have to weigh up the inconsistency of breaking the doc alias policy versus the inconsistency of offering the alises only on Unix.

SabrinaJewson · 2023-07-20T16:37:44Z

library/std/src/fs.rs

@@ -2038,6 +2046,10 @@ pub fn rename<P: AsRef<Path>, Q: AsRef<Path>>(from: P, to: Q) -> io::Result<()>
 ///     Ok(())
 /// }
 /// ```
+#[doc(alias = "cp")]
+#[doc(alias = "copy_file_range")]


Another instance of breaking the doc alias policy, where io::copy is also aliased to copy_file_range. I’m not sure which should win out here, because when a user wants to call copy_file_range they could plausibly end up calling either of these two functions.

library/std/src/fs.rs

SabrinaJewson · 2023-07-20T16:39:33Z

library/std/src/fs.rs

@@ -2276,6 +2289,7 @@ pub fn create_dir<P: AsRef<Path>>(path: P) -> io::Result<()> {
 ///     Ok(())
 /// }
 /// ```
+#[doc(alias = "mkdir", alias = "CreateDirectory")]


Another instance where we either choose to break the alias policy, or have to decide which one of create_dir vs create_dir_all “wins out” and gets the alias.

SabrinaJewson · 2023-07-20T16:40:17Z

library/std/src/os/windows/fs.rs

@@ -616,6 +617,7 @@ pub fn symlink_file<P: AsRef<Path>, Q: AsRef<Path>>(original: P, link: Q) -> io:
 /// the process as an administrator.
 ///
 /// [symlink-security]: https://docs.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/create-symbolic-links
+#[doc(alias = "CreateSymbolicLink", alias = "CreateSymbolicLinkW")]


A case similar to the create_dir[_all] case: Which one of these functions (symlink_file or symlink_dir) should win out and get to take the alias?

library/std/src/time.rs

joshtriplett · 2024-02-11T02:48:53Z

All of these seem fine to me, but need review and confirmation regarding the alias policy.

r? libs

Mark-Simulacrum · 2024-02-17T16:47:22Z

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?

SabrinaJewson · 2024-02-17T18:07:23Z

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.

I think it could still be useful — there’s some value in not having to think, just copypasting the name of a system function you’re looking at the docs of and getting taken exactly to its Rust wrapper. After all, isn’t that what the existing memcpy aliases are for?

I’m still interested in pushing this forward. The speed of this isn’t important to me, and I’m also not certain which parts are non-controversial, so I don’t immediately know how I would split this.

Mainly, I observed there was a steady stream of PRs adding specific doc aliases at random — this PR was made to bring everything in line at once.

Mark-Simulacrum · 2024-02-17T18:22:19Z

Let's do this:

Split out everything that's not commented on/referenced by comments. We can land those immediately.
Drop the aliases on the time types (or put those in a separate PR and I can nominate for libs-api discussion).
File a PR against https://github.com/rust-lang/std-dev-guide/blob/master/src/policy/doc-alias.md with revisions indicating that duplicates are OK where Rust has split functionality (e.g., File + Directory), but the underlying function is the same for both. I think that may make sense, we can discuss it there and then land those cases.

Hopefully that gives us an incremental path forward, anything not covered we can revisit once that's all squared away.

Thanks!

SabrinaJewson · 2024-02-18T13:58:48Z

library/std/src/fs.rs

@@ -2359,6 +2373,7 @@ pub fn remove_dir<P: AsRef<Path>>(path: P) -> io::Result<()> {
 ///     Ok(())
 /// }
 /// ```
+#[doc(alias = "rm")]


(seems like I forgot this one, it also breaks the policy).

SabrinaJewson · 2024-02-18T14:34:20Z

PRs have been filed. This PR is now blocked on rust-lang/std-dev-guide#64

…, r=Mark-Simulacrum Add uncontroversial syscall doc aliases to std docs This PR contains the parts of rust-lang#113891 that don’t break the doc alias policy. r? `@Mark-Simulacrum`

Rollup merge of rust-lang#121266 - SabrinaJewson:easy-syscall-aliases, r=Mark-Simulacrum Add uncontroversial syscall doc aliases to std docs This PR contains the parts of rust-lang#113891 that don’t break the doc alias policy. r? `@Mark-Simulacrum`

rustbot assigned joshtriplett Jul 20, 2023

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Jul 20, 2023

SabrinaJewson commented Jul 20, 2023

View reviewed changes

rustbot assigned Mark-Simulacrum and unassigned joshtriplett Feb 11, 2024

Mark-Simulacrum added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Feb 17, 2024

SabrinaJewson commented Feb 18, 2024

View reviewed changes

Add more syscall doc aliases to std docs

fbc92f0

SabrinaJewson force-pushed the more-syscall-aliases branch from 8d9f39e to fbc92f0 Compare February 18, 2024 14:13

rustbot added O-wasi Operating system: Wasi, Webassembly System Interface O-windows Operating system: Windows labels Feb 18, 2024

This was referenced Feb 18, 2024

Add uncontroversial syscall doc aliases to std docs #121266

Merged

Allow duplicate aliases in the doc alias policy rust-lang/std-dev-guide#64

Open

Remove std::time and ln syscall doc aliases

dcebd5c

Dylan-DPC added S-blocked Status: Blocked on something else such as an RFC or other implementation work. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Mar 17, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add more syscall doc aliases to std docs #113891

Add more syscall doc aliases to std docs #113891

SabrinaJewson commented Jul 20, 2023 •

edited by Dylan-DPC

Loading

rustbot commented Jul 20, 2023

SabrinaJewson left a comment

SabrinaJewson Jul 20, 2023

SabrinaJewson Jul 20, 2023

SabrinaJewson Jul 20, 2023

SabrinaJewson Jul 20, 2023 •

edited

Loading

joshtriplett commented Feb 11, 2024

Mark-Simulacrum commented Feb 17, 2024

SabrinaJewson commented Feb 17, 2024

Mark-Simulacrum commented Feb 17, 2024

SabrinaJewson Feb 18, 2024

SabrinaJewson commented Feb 18, 2024

Add more syscall doc aliases to std docs #113891

Are you sure you want to change the base?

Add more syscall doc aliases to std docs #113891

Conversation

SabrinaJewson commented Jul 20, 2023 • edited by Dylan-DPC Loading

rustbot commented Jul 20, 2023

SabrinaJewson left a comment

Choose a reason for hiding this comment

SabrinaJewson Jul 20, 2023

Choose a reason for hiding this comment

SabrinaJewson Jul 20, 2023

Choose a reason for hiding this comment

SabrinaJewson Jul 20, 2023

Choose a reason for hiding this comment

SabrinaJewson Jul 20, 2023 • edited Loading

Choose a reason for hiding this comment

joshtriplett commented Feb 11, 2024

Mark-Simulacrum commented Feb 17, 2024

SabrinaJewson commented Feb 17, 2024

Mark-Simulacrum commented Feb 17, 2024

SabrinaJewson Feb 18, 2024

Choose a reason for hiding this comment

SabrinaJewson commented Feb 18, 2024

SabrinaJewson commented Jul 20, 2023 •

edited by Dylan-DPC

Loading

SabrinaJewson Jul 20, 2023 •

edited

Loading