Auto merge of #108096 - matthiaskrgr:rollup-ncexzf6, r=matthiaskrgr

Rollup of 10 pull requests

Successful merges:

 - #107034 (Migrating rustc_infer to session diagnostics (part 4))
 - #107972 (Fix unintentional UB in ui tests)
 - #108010 (Make `InferCtxt::can_eq` and `InferCtxt::can_sub` return booleans)
 - #108021 (make x look for x.py if shell script does not exist)
 - #108047 (Use `target` instead of `machine` for mir interpreter integer handling.)
 - #108049 (Don't suggest `#[doc(hidden)]` trait methods with matching return type)
 - #108066 (Better names for illegal impl trait positions)
 - #108076 (rustdoc: Use more let chain)
 - #108088 (clarify correctness of `black_box`)
 - #108094 (Demonstrate I/O in File examples)

Failed merges:

r? `@ghost`
`@rustbot` modify labels: rollup

1 files changed, 19 insertions, 1 deletions

diff --git a/library/std/src/fs.rs b/library/std/src/fs.rs
index 286ad68fd13..c550378e7d6 100644
--- a/library/std/src/fs.rs
+++ b/library/std/src/fs.rs
@@ -334,6 +334,10 @@ impl File {
     ///
     /// See the [`OpenOptions::open`] method for more details.
     ///
+    /// If you only need to read the entire file contents,
+    /// consider [`std::fs::read()`][self::read] or
+    /// [`std::fs::read_to_string()`][self::read_to_string] instead.
+    ///
     /// # Errors
     ///
     /// This function will return an error if `path` does not already exist.
@@ -343,9 +347,12 @@ impl File {
     ///
     /// ```no_run
     /// use std::fs::File;
+    /// use std::io::Read;
     ///
     /// fn main() -> std::io::Result<()> {
     ///     let mut f = File::open("foo.txt")?;
+    ///     let mut data = vec![];
+    ///     f.read_to_end(&mut data)?;
     ///     Ok(())
     /// }
     /// ```
@@ -361,16 +368,20 @@ impl File {
     ///
     /// Depending on the platform, this function may fail if the
     /// full directory path does not exist.
-    ///
     /// See the [`OpenOptions::open`] function for more details.
     ///
+    /// See also [`std::fs::write()`][self::write] for a simple function to
+    /// create a file with a given data.
+    ///
     /// # Examples
     ///
     /// ```no_run
     /// use std::fs::File;
+    /// use std::io::Write;
     ///
     /// fn main() -> std::io::Result<()> {
     ///     let mut f = File::create("foo.txt")?;
+    ///     f.write_all(&1234_u32.to_be_bytes())?;
     ///     Ok(())
     /// }
     /// ```
@@ -397,9 +408,11 @@ impl File {
     /// #![feature(file_create_new)]
     ///
     /// use std::fs::File;
+    /// use std::io::Write;
     ///
     /// fn main() -> std::io::Result<()> {
     ///     let mut f = File::create_new("foo.txt")?;
+    ///     f.write_all("Hello, world!".as_bytes())?;
     ///     Ok(())
     /// }
     /// ```
@@ -426,9 +439,11 @@ impl File {
     ///
     /// ```no_run
     /// use std::fs::File;
+    /// use std::io::Write;
     ///
     /// fn main() -> std::io::Result<()> {
     ///     let mut f = File::options().append(true).open("example.log")?;
+    ///     writeln!(&mut f, "new line")?;
     ///     Ok(())
     /// }
     /// ```
@@ -966,6 +981,9 @@ impl OpenOptions {
     /// In order for the file to be created, [`OpenOptions::write`] or
     /// [`OpenOptions::append`] access must be used.
     ///
+    /// See also [`std::fs::write()`][self::write] for a simple function to
+    /// create a file with a given data.
+    ///
     /// # Examples
     ///
     /// ```no_run