Added platform notes to std::fs public functions.

[nathansizemore]

#29359

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @aturon (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. The way Github handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[steveklabnik]

Interesting. One of the things about this PR is that we need to figure out the standard way to encode this kind of thing, I guess a link to github would be reasonable.

Two nits here: 1: this needs to be []() not [][], and the period should be outside the link. However, we prefer the reference style links, like

/// [may change in the future][changes].
///
/// [changes]: url 

So that should be done, regardless.

[steveklabnik]

Thank you so much for taking this on! A few nits, and I'd like @rust-lang/libs to take a look as well.

[steveklabnik]

It might be worth adding this new standard header to https://doc.rust-lang.org/book/documentation.html#special-sections too

[nathansizemore]

Whoops, guess I got in a hurry and totally over looked placing the links at the bottom :(
I'll get this stuff edited and push up again

[steveklabnik]

it's all good! This is exactly why we do review :)

[nathansizemore]

Once there has been enough discussion and decision on what the title for the section actually should be, I'll get it into the special sections too.

[alexcrichton]

Looking good to me! I like @steveklabnik's idea about "Platform-specific behavior" as a heading, and I think that this may also want to just have a dedicated section of the std::io docs or something like that as a URL for reference (rather than the previous PR). For example something like:

Platform-specific behavior

Many I/O functions throughout the standard library are documented to indicate what various library or syscalls they are delegated to. This is done to help applications both understand what's happening under the hood as well as investigate any possibly unclear semantics. Note, however, that this is informative, not a binding contract. The implementation of many of these functions are subject to change over time and may call fewer or more syscalls/library functions.

[bors]

☔ The latest upstream changes (presumably #30588) made this pull request unmergeable. Please resolve the merge conflicts.

[steveklabnik]

@nathansizemore sorry, github doesn't update us when a commit gets pushed, so i missed this! There's merge conficts now, so would you mind rebasing, and then we can land this? Thanks!

[nathansizemore]

@steveklabnik should be ready to go!

[steveklabnik]

@bors: r+ rollup

Thanks so much!

[bors]

📌 Commit 3e9d5fe has been approved by steveklabnik

[bors]

⌛ Testing commit 3e9d5fe with merge 720afe5...

[bors]

💔 Test failed - auto-linux-64-nopt-t

[sfackler]

@bors retry

[bors]

⌛ Testing commit 3e9d5fe with merge 99e59de...

[bors]

☀️ Test successful - auto-linux-32-nopt-t, auto-linux-32-opt, auto-linux-64-debug-opt, auto-linux-64-nopt-t, auto-linux-64-opt, auto-linux-64-x-android-t, auto-linux-cross-opt, auto-linux-musl-64-opt, auto-mac-32-opt, auto-mac-64-nopt-t, auto-mac-64-opt, auto-win-gnu-32-nopt-t, auto-win-gnu-32-opt, auto-win-gnu-64-nopt-t, auto-win-gnu-64-opt, auto-win-msvc-32-opt, auto-win-msvc-64-opt

[aturon]

\o/