Add std::fs::write documentation precision #98662
Conversation
rustbot
added
the
T-libs
|
Hey! It looks like you've submitted a new PR for the library teams! If this PR contains changes to any Examples of
|
|
r? @thomcc (rust-highfive has picked a reviewer for you, use r? to override) |
rust-highfive
added
the
S-waiting-on-review
library/std/src/fs.rs
Outdated
| @@ -295,6 +295,9 @@ pub fn read_to_string<P: AsRef<Path>>(path: P) -> io::Result<String> { | |||
| /// This function will create a file if it does not exist, | |||
| /// and will entirely replace its contents if it does. | |||
| /// | |||
| /// However, if a parent directory in the path doesn't exist, | |||
| /// the function will fail. | |||
There was a problem hiding this comment.
I think this can be simplified by folding it into the previous paragraph. Something along the lines of
[...] will create a file if it does not exist - but only if the directory itself exists - and will [...]
There was a problem hiding this comment.
Indeed, but if we take what @thomcc said into account and introduce hypothetical platforms, this will become hard to fold in the previous paragraph without hindering the readability.
|
Do we care at all about any hypothetical platforms where this isn't the case? |
|
I think this counts as a new guarantee. My only hesitation here is that while this is extremely reasonable and guaranteed on all current platforms (I think?), I think it also would not really be possible for us to implement this guarantee inside the stdlib, without race conditions. Not really sure what to do about this, though. @rustbot label +T-libs-api -T-libs |
rustbot
added
T-libs-api
|
You can always water it down with a "might not" or something like that. |
|
As this is documented to be a wrapper around |
|
If we aren't guaranteeing this (e.g. say "might not"), then yeah, I don't think this needs API sign off. So, can you reduce the guarantee to "might not" (as suggested by #98662 (comment)), and also, add a similar comment to File::create (as suggested by #98662 (comment))? |
LucasDumont
force-pushed
the
document_fs_write
branch
from
a6c171b
to
c0c7d13
Compare
LucasDumont
force-pushed
the
document_fs_write
branch
from
c0c7d13
to
64c696c
Compare
As mentioned in rust-lang#97947, the documentation is updated
LucasDumont
force-pushed
the
document_fs_write
branch
from
64c696c
to
07a0fd2
Compare
|
@bors r+ rollup |
bors
added
S-waiting-on-bors
…omcc Add std::fs::write documentation precision Fixes rust-lang#97947. As mentioned in rust-lang#97947, the documentation is updated
Rollup of 7 pull requests Successful merges: - rust-lang#98387 (Add new unstable API `downcast` to `std::io::Error`) - rust-lang#98662 (Add std::fs::write documentation precision) - rust-lang#99253 (Remove FIXME from MIR `always_storage_live_locals`) - rust-lang#99264 (Fix typo in mod.rs) - rust-lang#99270 (Add `#[must_use]` to `Box::from_raw`) - rust-lang#99277 (Stabilize `core::ffi::CStr`, `alloc::ffi::CString`, and friends) - rust-lang#99307 (Add regression test for rust-lang#64401) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup
Fixes #97947.
As mentioned in #97947, the documentation is updated