From 2f1e1be6ffbf39e3a7b219343e4be38cab599cf4 Mon Sep 17 00:00:00 2001 From: Julius Liu Date: Mon, 9 Sep 2024 11:55:44 -0700 Subject: [PATCH 1/4] maint: update docs for change_time ext and doc links --- library/std/src/os/windows/fs.rs | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/library/std/src/os/windows/fs.rs b/library/std/src/os/windows/fs.rs index 7cac8c39ea8..285d9c3fc78 100644 --- a/library/std/src/os/windows/fs.rs +++ b/library/std/src/os/windows/fs.rs @@ -299,7 +299,7 @@ fn security_qos_flags(&mut self, flags: u32) -> &mut OpenOptions { /// of the [`BY_HANDLE_FILE_INFORMATION`] structure. /// /// [`BY_HANDLE_FILE_INFORMATION`]: -/// https://docs.microsoft.com/en-us/windows/win32/api/fileapi/ns-fileapi-by_handle_file_information +/// https://docs.microsoft.com/windows/win32/api/fileapi/ns-fileapi-by_handle_file_information #[stable(feature = "metadata_ext", since = "1.1.0")] pub trait MetadataExt { /// Returns the value of the `dwFileAttributes` field of this metadata. @@ -323,7 +323,7 @@ pub trait MetadataExt { /// ``` /// /// [File Attribute Constants]: - /// https://docs.microsoft.com/en-us/windows/win32/fileio/file-attribute-constants + /// https://docs.microsoft.com/windows/win32/fileio/file-attribute-constants #[stable(feature = "metadata_ext", since = "1.1.0")] fn file_attributes(&self) -> u32; @@ -352,7 +352,7 @@ pub trait MetadataExt { /// } /// ``` /// - /// [`FILETIME`]: https://docs.microsoft.com/en-us/windows/win32/api/minwinbase/ns-minwinbase-filetime + /// [`FILETIME`]: https://docs.microsoft.com/windows/win32/api/minwinbase/ns-minwinbase-filetime #[stable(feature = "metadata_ext", since = "1.1.0")] fn creation_time(&self) -> u64; @@ -387,7 +387,7 @@ pub trait MetadataExt { /// } /// ``` /// - /// [`FILETIME`]: https://docs.microsoft.com/en-us/windows/win32/api/minwinbase/ns-minwinbase-filetime + /// [`FILETIME`]: https://docs.microsoft.com/windows/win32/api/minwinbase/ns-minwinbase-filetime #[stable(feature = "metadata_ext", since = "1.1.0")] fn last_access_time(&self) -> u64; @@ -420,7 +420,7 @@ pub trait MetadataExt { /// } /// ``` /// - /// [`FILETIME`]: https://docs.microsoft.com/en-us/windows/win32/api/minwinbase/ns-minwinbase-filetime + /// [`FILETIME`]: https://docs.microsoft.com/windows/win32/api/minwinbase/ns-minwinbase-filetime #[stable(feature = "metadata_ext", since = "1.1.0")] fn last_write_time(&self) -> u64; @@ -472,10 +472,21 @@ pub trait MetadataExt { #[unstable(feature = "windows_by_handle", issue = "63010")] fn file_index(&self) -> Option; - /// Returns the change time, which is the last time file metadata was changed, such as - /// renames, attributes, etc + /// Returns the value of the `ChangeTime{Low,High}` field from the + /// [`FILE_BASIC_INFO`] struct associated with the current file handle. + /// [`ChangeTime`] is the last time file metadata was changed, such as + /// renames, attributes, etc. /// - /// This will return `None` if the `Metadata` instance was not created using the `FILE_BASIC_INFO` type. + /// This will return `None` if `Metadata` was populated without access to + /// [`FILE_BASIC_INFO`]. For example, the result of `std::fs::read_dir` + /// will be derived from [`WIN32_FIND_DATA`] which does not have access to + /// `ChangeTime`. + /// + /// [`FILE_BASIC_INFO`]: https://learn.microsoft.com/windows/win32/api/winbase/ns-winbase-file_basic_info + /// [`WIN32_FIND_DATA`]: https://learn.microsoft.com/windows/win32/api/minwinbase/ns-minwinbase-win32_find_dataw + /// [`FindFirstFile`]: https://learn.microsoft.com/windows/win32/api/fileapi/nf-fileapi-findfirstfilea + /// [`FindNextFile`]: https://learn.microsoft.com/windows/win32/api/fileapi/nf-fileapi-findnextfilea + /// [`ChangeTime`]: https://devblogs.microsoft.com/oldnewthing/20100709-00/?p=13463. #[unstable(feature = "windows_change_time", issue = "121478")] fn change_time(&self) -> Option; } From a0a89e55387dc4291442e5fc401bd1e35b94fbe8 Mon Sep 17 00:00:00 2001 From: Julius Liu Date: Mon, 9 Sep 2024 13:56:41 -0700 Subject: [PATCH 2/4] chore: removing supporting links in favor of existing doc-comment style --- library/std/src/os/windows/fs.rs | 19 ++++++------------- 1 file changed, 6 insertions(+), 13 deletions(-) diff --git a/library/std/src/os/windows/fs.rs b/library/std/src/os/windows/fs.rs index 285d9c3fc78..d03f9e0e330 100644 --- a/library/std/src/os/windows/fs.rs +++ b/library/std/src/os/windows/fs.rs @@ -472,21 +472,14 @@ pub trait MetadataExt { #[unstable(feature = "windows_by_handle", issue = "63010")] fn file_index(&self) -> Option; - /// Returns the value of the `ChangeTime{Low,High}` field from the - /// [`FILE_BASIC_INFO`] struct associated with the current file handle. - /// [`ChangeTime`] is the last time file metadata was changed, such as + /// Returns the value of the `ChangeTime{Low,High}` fields of this metadata. + /// + /// `ChangeTime` is the last time file metadata was changed, such as /// renames, attributes, etc. /// - /// This will return `None` if `Metadata` was populated without access to - /// [`FILE_BASIC_INFO`]. For example, the result of `std::fs::read_dir` - /// will be derived from [`WIN32_FIND_DATA`] which does not have access to - /// `ChangeTime`. - /// - /// [`FILE_BASIC_INFO`]: https://learn.microsoft.com/windows/win32/api/winbase/ns-winbase-file_basic_info - /// [`WIN32_FIND_DATA`]: https://learn.microsoft.com/windows/win32/api/minwinbase/ns-minwinbase-win32_find_dataw - /// [`FindFirstFile`]: https://learn.microsoft.com/windows/win32/api/fileapi/nf-fileapi-findfirstfilea - /// [`FindNextFile`]: https://learn.microsoft.com/windows/win32/api/fileapi/nf-fileapi-findnextfilea - /// [`ChangeTime`]: https://devblogs.microsoft.com/oldnewthing/20100709-00/?p=13463. + /// This will return `None` if `Metadata` instance was created from a call to + /// `DirEntry::metadata` or if the `target_vendor` is outside the current platform + /// support for this api. #[unstable(feature = "windows_change_time", issue = "121478")] fn change_time(&self) -> Option; } From 6c8423865f65fd11ee42d33336a349b9817a02ff Mon Sep 17 00:00:00 2001 From: Julius Liu Date: Wed, 11 Sep 2024 09:59:05 -0700 Subject: [PATCH 3/4] docs: remove struct info --- library/std/src/os/windows/fs.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/std/src/os/windows/fs.rs b/library/std/src/os/windows/fs.rs index d03f9e0e330..c3b91967953 100644 --- a/library/std/src/os/windows/fs.rs +++ b/library/std/src/os/windows/fs.rs @@ -472,7 +472,7 @@ pub trait MetadataExt { #[unstable(feature = "windows_by_handle", issue = "63010")] fn file_index(&self) -> Option; - /// Returns the value of the `ChangeTime{Low,High}` fields of this metadata. + /// Returns the value of the `ChangeTime` fields of this metadata. /// /// `ChangeTime` is the last time file metadata was changed, such as /// renames, attributes, etc. From 5527076d84ae874d726f3bf03f83bd1db2cfb199 Mon Sep 17 00:00:00 2001 From: Julius Liu Date: Wed, 11 Sep 2024 12:00:03 -0700 Subject: [PATCH 4/4] chore: remove struct details --- library/std/src/os/windows/fs.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/library/std/src/os/windows/fs.rs b/library/std/src/os/windows/fs.rs index c3b91967953..9ea33e31f2c 100644 --- a/library/std/src/os/windows/fs.rs +++ b/library/std/src/os/windows/fs.rs @@ -424,7 +424,7 @@ pub trait MetadataExt { #[stable(feature = "metadata_ext", since = "1.1.0")] fn last_write_time(&self) -> u64; - /// Returns the value of the `nFileSize{High,Low}` fields of this + /// Returns the value of the `nFileSize` fields of this /// metadata. /// /// The returned value does not have meaning for directories. @@ -463,7 +463,7 @@ pub trait MetadataExt { #[unstable(feature = "windows_by_handle", issue = "63010")] fn number_of_links(&self) -> Option; - /// Returns the value of the `nFileIndex{Low,High}` fields of this + /// Returns the value of the `nFileIndex` fields of this /// metadata. /// /// This will return `None` if the `Metadata` instance was created from a