Rollup merge of rust-lang#123756 - lukas-code:file-sync, r=jhpratt

clean up docs for `File::sync_*`

* Clarify that `sync_all` also writes data and not just metadata.
* Clarify that dropping a file is not equivalent to calling `sync_all` and ignoring the result. `sync_all` the still the recommended way to detect errors before closing, because we don't have a dedicated method for that.
* Add a link from `sync_all` to `sync_data`, because that's what the user might want to use instead.
* Add doc aliases for `fsync` -> `sync_all` and `fdatasync` -> `sync_data`. Those are the POSIX standard names for these functions. I was trying to find out what we call `fsync` in Rust and had to search through the source code to find it, so this alias should help with that in the future.

Author: fmease

library/std/src/fs.rs

@@ -465,14 +465,20 @@ impl File {
         OpenOptions::new()
     }
 
-    /// Attempts to sync all OS-internal metadata to disk.
+    /// Attempts to sync all OS-internal file content and metadata to disk.
     ///
     /// This function will attempt to ensure that all in-memory data reaches the
     /// filesystem before returning.
     ///
     /// This can be used to handle errors that would otherwise only be caught
-    /// when the `File` is closed.  Dropping a file will ignore errors in
-    /// synchronizing this in-memory data.
+    /// when the `File` is closed, as dropping a `File` will ignore all errors.
+    /// Note, however, that `sync_all` is generally more expensive than closing
+    /// a file by dropping it, because the latter is not required to block until
+    /// the data has been written to the filesystem.
+    ///
+    /// If synchronizing the metadata is not required, use [`sync_data`] instead.
+    ///
+    /// [`sync_data`]: File::sync_data
     ///
     /// # Examples
     ///
@@ -489,6 +495,7 @@ impl File {
     /// }
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
+    #[doc(alias = "fsync")]
     pub fn sync_all(&self) -> io::Result<()> {
         self.inner.fsync()
     }
@@ -520,6 +527,7 @@ impl File {
     /// }
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
+    #[doc(alias = "fdatasync")]
     pub fn sync_data(&self) -> io::Result<()> {
         self.inner.datasync()
     }