From ca86f0b2a4b3d16140f7c184f0a6c03ab68c60b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20S=C3=A1nchez=20L=C3=B3pez?= <1175054+carlossanlop@users.noreply.github.com> Date: Tue, 6 Aug 2024 15:33:14 -0700 Subject: [PATCH 1/4] System.IO --- xml/System.IO/File.xml | 303 ++++++++++++++++++++++++++------- xml/System.IO/Path.xml | 12 +- xml/System.IO/StreamWriter.xml | 12 +- xml/System.IO/TextWriter.xml | 30 ++-- 4 files changed, 274 insertions(+), 83 deletions(-) diff --git a/xml/System.IO/File.xml b/xml/System.IO/File.xml index ca18a64fcd9..2511de8c1f3 100644 --- a/xml/System.IO/File.xml +++ b/xml/System.IO/File.xml @@ -150,10 +150,32 @@ - To be added. - To be added. - To be added. + The file to append to. + The bytes to append to the file. + + Appends the specified byte array to the end of the file at the given path. + If the file doesn't exist, this method creates a new file. + To be added. + + is . + + is . + + is empty. + The specified path, file name, or both exceed the system-defined maximum length. + The specified path is invalid (for example, it is on an unmapped drive). + An I/O error occurred while opening the file. + + specified a file that is read-only. + + specified a file that is hidden. + + specified a directory. + The caller does not have the required permission. + This operation is not supported on the current platform. + + is in an invalid format. @@ -195,10 +217,30 @@ - To be added. - To be added. - To be added. + The file to append to. + The bytes to append to the file. + + Appends the specified byte array to the end of the file at the given path. + If the file doesn't exist, this method creates a new file. + To be added. + + is . + + is empty. + The specified path, file name, or both exceed the system-defined maximum length. + The specified path is invalid (for example, it is on an unmapped drive). + An I/O error occurred while opening the file. + + specified a file that is read-only. + + specified a file that is hidden. + + specified a directory. + The caller does not have the required permission. + This operation is not supported on the current platform. + + is in an invalid format. @@ -230,12 +272,22 @@ - To be added. - To be added. - To be added. - To be added. + The file to append to. + The bytes to append to the file. + The token to monitor for cancellation requests. The default value is . + + Asynchronously appends the specified byte array to the end of the file at the given path. + If the file doesn't exist, this method creates a new file. If the operation is canceled, the task will return in a canceled state. + To be added. To be added. + + is . + + is . + + is empty. + The cancellation token was canceled. This exception is stored into the returned task. @@ -271,12 +323,20 @@ - To be added. - To be added. - To be added. - To be added. + The file to append to. + The bytes to append to the file. + The token to monitor for cancellation requests. The default value is . + + Asynchronously appends the specified byte array to the end of the file at the given path. + If the file doesn't exist, this method creates a new file. If the operation is canceled, the task will return in a canceled state. + To be added. To be added. + + is . + + is empty. + The cancellation token was canceled. This exception is stored into the returned task. @@ -619,10 +679,31 @@ - To be added. - To be added. - To be added. - To be added. + The file to append to. + The characters to write to the file. + Appends the specified string to the file, creating the file if it does not already exist. + + Given a string and a file path, this method opens the specified file, appends the string to the end of the file using the specified encoding, + and then closes the file. The file handle is guaranteed to be closed by this method, even if exceptions are raised. The method creates the file + if it doesn't exist, but it doesn't create new directories. Therefore, the value of the path parameter must contain existing directories. + + + is . + + is empty. + The specified path, file name, or both exceed the system-defined maximum length. + The specified path is invalid (for example, it is on an unmapped drive). + An I/O error occurred while opening the file. + + specified a file that is read-only. + + specified a file that is hidden. + + specified a directory. + This operation is not supported on the current platform. + The caller does not have the required permission. + + is in an invalid format. @@ -763,11 +844,34 @@ - To be added. - To be added. - To be added. - To be added. - To be added. + The file to append to. + The characters to write to the file. + The encoding to apply to the string. + Appends the specified string to the file, creating the file if it does not already exist. + + Given a string and a file path, this method opens the specified file, appends the string to the end of the file using the specified encoding, + and then closes the file. The file handle is guaranteed to be closed by this method, even if exceptions are raised. The method creates the file + if it doesn't exist, but it doesn't create new directories. Therefore, the value of the path parameter must contain existing directories. + + + is . + + is empty. + + is . + The specified path, file name, or both exceed the system-defined maximum length. + The specified path is invalid (for example, it is on an unmapped drive). + An I/O error occurred while opening the file. + + specified a file that is read-only. + + specified a file that is hidden. + + specified a directory. + This operation is not supported on the current platform. + The caller does not have the required permission. + + is in an invalid format. @@ -909,12 +1013,13 @@ - To be added. - To be added. - To be added. - To be added. - To be added. + The file to append the specified string to. + The characters to append to the file. + The token to monitor for cancellation requests. The default value is . + Asynchronously opens a file or creates a file if it does not already exist, appends the specified string to the file, and then closes the file. + A task that represents the asynchronous append operation. To be added. + The cancellation token was canceled. This exception is stored into the returned task. @@ -1005,13 +1110,14 @@ - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + The file to append the specified string to. + The characters to append to the file. + The character encoding to use. + The token to monitor for cancellation requests. The default value is . + Asynchronously opens a file or creates the file if it does not already exist, appends the specified string to the file using the specified encoding, and then closes the file. + A task that represents the asynchronous append operation. To be added. + The cancellation token was canceled. This exception is stored into the returned task. @@ -6908,10 +7014,27 @@ It is not possible to change the compression status of a o - To be added. - To be added. - To be added. + The file to write to. + The bytes to write to the file. + Creates a new file, writes the specified byte array to the file, and then closes the file. If the target file already exists, it is truncated and overwritten. To be added. + + is . + + is empty. + The specified path, file name, or both exceed the system-defined maximum length. + The specified path is invalid (for example, it is on an unmapped drive). + An I/O error occurred while opening the file. + + specified a file that is read-only. + + specified a file that is hidden. + + specified a directory. + The caller does not have the required permission. + This operation is not supported on the current platform. + + is in an invalid format. @@ -6993,12 +7116,17 @@ It is not possible to change the compression status of a o - To be added. - To be added. - To be added. - To be added. - To be added. + The file to write to. + The bytes to write to the file. + The token to monitor for cancellation requests. The default value is . + Asynchronously creates a new file, writes the specified byte array to the file, and then closes the file. If the target file already exists, it is truncated and overwritten. + A task that represents the asynchronous write operation. To be added. + + is . + + is empty. + The cancellation token was canceled. This exception is stored into the returned task. @@ -7551,10 +7679,33 @@ It is not possible to change the compression status of a o - To be added. - To be added. - To be added. - To be added. + The file to write to. + The characters to write to the file. + + Creates a new file, writes the specified string to the file, and then closes the file. + If the target file already exists, it is truncated and overwritten. + + + This method uses UTF-8 encoding without a Byte-Order Mark (BOM), so using the GetPreamble method will return an empty byte array. If it is necessary to + include a UTF-8 identifier, such as a byte order mark, at the beginning of a file, use the method. + + + is . + + is empty. + The specified path, file name, or both exceed the system-defined maximum length. + The specified path is invalid (for example, it is on an unmapped drive). + An I/O error occurred while opening the file. + + specified a file that is read-only. + + specified a file that is hidden. + + specified a directory. + This operation is not supported on the current platform. + The caller does not have the required permission. + + is in an invalid format. @@ -7699,11 +7850,33 @@ It is not possible to change the compression status of a o - To be added. - To be added. - To be added. - To be added. + The file to write to. + The characters to write to the file. + The encoding to apply to the string. + + Creates a new file, writes the specified string to the file using the specified encoding, and then closes the file. + If the target file already exists, it is truncated and overwritten. + To be added. + + is . + + is empty. + + is . + The specified path, file name, or both exceed the system-defined maximum length. + The specified path is invalid (for example, it is on an unmapped drive). + An I/O error occurred while opening the file. + + specified a file that is read-only. + + specified a file that is hidden. + + specified a directory. + This operation is not supported on the current platform. + The caller does not have the required permission. + + is in an invalid format. @@ -7847,12 +8020,16 @@ It is not possible to change the compression status of a o - To be added. - To be added. - To be added. - To be added. - To be added. + The file to write to. + The characters to write to the file. + The token to monitor for cancellation requests. The default value is . + + Asynchronously creates a new file, writes the specified string to the file, and then closes the file. + If the target file already exists, it is truncated and overwritten. + + A task that represents the asynchronous write operation. To be added. + The cancellation token was canceled. This exception is stored into the returned task. @@ -7943,13 +8120,17 @@ It is not possible to change the compression status of a o - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + The file to write to. + The characters to write to the file. + The encoding to apply to the string. + The token to monitor for cancellation requests. The default value is . + + Asynchronously creates a new file, writes the specified string to the file using the specified encoding, and then closes the file. + If the target file already exists, it is truncated and overwritten. + + A task that represents the asynchronous write operation. To be added. + The cancellation token was canceled. This exception is stored into the returned task. diff --git a/xml/System.IO/Path.xml b/xml/System.IO/Path.xml index d362edd8a3a..573ad4d7da5 100644 --- a/xml/System.IO/Path.xml +++ b/xml/System.IO/Path.xml @@ -355,9 +355,9 @@ This method is intended to concatenate individual strings into a single string t - To be added. - To be added. - To be added. + A span of parts of the path. + Combines a span of strings into a path. + The combined paths. To be added. @@ -2890,9 +2890,9 @@ Note that rooted paths can be either absolute (that is, fully qualified) or rela - To be added. - To be added. - To be added. + A span of paths. + Concatenates a span of paths into a single path. + The concatenated path. To be added. diff --git a/xml/System.IO/StreamWriter.xml b/xml/System.IO/StreamWriter.xml index a18ac46a6e7..6e5e92b77d7 100644 --- a/xml/System.IO/StreamWriter.xml +++ b/xml/System.IO/StreamWriter.xml @@ -2117,9 +2117,9 @@ See for a descr - To be added. - To be added. - To be added. + A composite format string. + An object span that contains zero or more objects to format and write. + Writes a formatted string to the stream, using the same semantics as . To be added. @@ -2976,9 +2976,9 @@ See for a d - To be added. - To be added. - To be added. + A composite format string. + An object span that contains zero or more objects to format and write. + Writes out a formatted string and a new line to the stream, using the same semantics as . To be added. diff --git a/xml/System.IO/TextWriter.xml b/xml/System.IO/TextWriter.xml index e8c5c42b973..295ace95eba 100644 --- a/xml/System.IO/TextWriter.xml +++ b/xml/System.IO/TextWriter.xml @@ -439,10 +439,20 @@ - To be added. - To be added. - To be added. - To be added. + The instances to which all operations should be broadcast (multiplexed). + Creates an instance of that writes supplied inputs to each of the writers in . + An instance of that writes supplied inputs to each of the writers in + + The resulting instance will delegate each operation to each of the writers in . + For example, calling will write the specified char to each writer, one after the + other. The writers will be written to in the same order as they are specified in . + An exception from the operation on one writer will prevent the operation from being performed on subsequent writers. + + and will return the corresponding object from first writer + in . + + + is or it contains a . @@ -2470,9 +2480,9 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the - To be added. - To be added. - To be added. + A composite format string. + An object span that contains zero or more objects to format and write. + Writes a formatted string to the text stream, using the same semantics as . To be added. @@ -4627,9 +4637,9 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo - To be added. - To be added. - To be added. + A composite format string. + An object span that contains zero or more objects to format and write. + Writes out a formatted string and a new line to the text stream, using the same semantics as . To be added. From 7d80d0d53d452f744f9ca098b984c436c9866c2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20S=C3=A1nchez=20L=C3=B3pez?= <1175054+carlossanlop@users.noreply.github.com> Date: Wed, 7 Aug 2024 12:46:15 -0700 Subject: [PATCH 2/4] Address suggestions --- xml/System.IO/File.xml | 77 +++++++++++++++++++++++------------- xml/System.IO/TextWriter.xml | 11 ++---- 2 files changed, 52 insertions(+), 36 deletions(-) diff --git a/xml/System.IO/File.xml b/xml/System.IO/File.xml index 2511de8c1f3..81f2a65975d 100644 --- a/xml/System.IO/File.xml +++ b/xml/System.IO/File.xml @@ -158,22 +158,30 @@ To be added. - is . - - is . + or is . + is empty. The specified path, file name, or both exceed the system-defined maximum length. The specified path is invalid (for example, it is on an unmapped drive). An I/O error occurred while opening the file. - specified a file that is read-only. - - specified a file that is hidden. - - specified a directory. - The caller does not have the required permission. - This operation is not supported on the current platform. + + specified a file that is read-only. + + -or- + + specified a file that is hidden. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. + -or- + This operation is not supported on the current platform. + is in an invalid format. @@ -232,13 +240,21 @@ The specified path is invalid (for example, it is on an unmapped drive). An I/O error occurred while opening the file. - specified a file that is read-only. - - specified a file that is hidden. - - specified a directory. - The caller does not have the required permission. - This operation is not supported on the current platform. + + specified a file that is read-only. + + -or- + + specified a file that is hidden. + + -or- + + specified a directory. + + The caller does not have the required permission. + -or- + This operation is not supported on the current platform. + is in an invalid format. @@ -7685,10 +7701,7 @@ It is not possible to change the compression status of a o Creates a new file, writes the specified string to the file, and then closes the file. If the target file already exists, it is truncated and overwritten. - - This method uses UTF-8 encoding without a Byte-Order Mark (BOM), so using the GetPreamble method will return an empty byte array. If it is necessary to - include a UTF-8 identifier, such as a byte order mark, at the beginning of a file, use the method. - + This method uses UTF-8 encoding without a Byte-Order Mark (BOM), so using the GetPreamble method will return an empty byte array. If it is necessary to include a UTF-8 identifier, such as a byte order mark, at the beginning of a file, use the method. is . @@ -7697,13 +7710,21 @@ It is not possible to change the compression status of a o The specified path is invalid (for example, it is on an unmapped drive). An I/O error occurred while opening the file. - specified a file that is read-only. - - specified a file that is hidden. - - specified a directory. - This operation is not supported on the current platform. - The caller does not have the required permission. + + specified a file that is read-only. + + -or- + + specified a file that is hidden. + + -or- + + specified a directory. + + -or- + This operation is not supported on the current platform. + The caller does not have the required permission. + is in an invalid format. diff --git a/xml/System.IO/TextWriter.xml b/xml/System.IO/TextWriter.xml index 295ace95eba..f1a05c07869 100644 --- a/xml/System.IO/TextWriter.xml +++ b/xml/System.IO/TextWriter.xml @@ -443,14 +443,9 @@ Creates an instance of that writes supplied inputs to each of the writers in . An instance of that writes supplied inputs to each of the writers in - The resulting instance will delegate each operation to each of the writers in . - For example, calling will write the specified char to each writer, one after the - other. The writers will be written to in the same order as they are specified in . - An exception from the operation on one writer will prevent the operation from being performed on subsequent writers. - - and will return the corresponding object from first writer - in . - + The resulting instance will delegate each operation to each of the writers in . For example, calling will write the specified char to each writer, one after the other. The writers will be written to in the same order as they are specified in . An exception from the operation on one writer will prevent the operation from being performed on subsequent writers. + and will return the corresponding object from first writer in . + is or it contains a . From 2ae71690f75440dbacce41fadebff605c7dce9a8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20S=C3=A1nchez=20L=C3=B3pez?= <1175054+carlossanlop@users.noreply.github.com> Date: Fri, 9 Aug 2024 12:48:20 -0700 Subject: [PATCH 3/4] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: David Cantú --- xml/System.IO/File.xml | 109 +++++++++++++++++++++++++++-------------- 1 file changed, 71 insertions(+), 38 deletions(-) diff --git a/xml/System.IO/File.xml b/xml/System.IO/File.xml index 81f2a65975d..21baaf2a5ac 100644 --- a/xml/System.IO/File.xml +++ b/xml/System.IO/File.xml @@ -298,9 +298,8 @@ To be added. To be added. - is . - - is . + or is . + is empty. The cancellation token was canceled. This exception is stored into the returned task. @@ -711,13 +710,22 @@ The specified path is invalid (for example, it is on an unmapped drive). An I/O error occurred while opening the file. - specified a file that is read-only. - - specified a file that is hidden. - - specified a directory. - This operation is not supported on the current platform. - The caller does not have the required permission. + + specified a file that is read-only. + + -or- + + specified a file that is hidden. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. + -or- + This operation is not supported on the current platform. + is in an invalid format. @@ -870,22 +878,30 @@ if it doesn't exist, but it doesn't create new directories. Therefore, the value of the path parameter must contain existing directories. - is . + or is . + is empty. - - is . The specified path, file name, or both exceed the system-defined maximum length. The specified path is invalid (for example, it is on an unmapped drive). An I/O error occurred while opening the file. - specified a file that is read-only. - - specified a file that is hidden. - - specified a directory. - This operation is not supported on the current platform. - The caller does not have the required permission. + + specified a file that is read-only. + + -or- + + specified a file that is hidden. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. + -or- + This operation is not supported on the current platform. + is in an invalid format. @@ -7042,13 +7058,22 @@ It is not possible to change the compression status of a o The specified path is invalid (for example, it is on an unmapped drive). An I/O error occurred while opening the file. - specified a file that is read-only. - - specified a file that is hidden. - - specified a directory. - The caller does not have the required permission. - This operation is not supported on the current platform. + + specified a file that is read-only. + + -or- + + specified a file that is hidden. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. + -or- + This operation is not supported on the current platform. + is in an invalid format. @@ -7701,7 +7726,7 @@ It is not possible to change the compression status of a o Creates a new file, writes the specified string to the file, and then closes the file. If the target file already exists, it is truncated and overwritten. - This method uses UTF-8 encoding without a Byte-Order Mark (BOM), so using the GetPreamble method will return an empty byte array. If it is necessary to include a UTF-8 identifier, such as a byte order mark, at the beginning of a file, use the method. + This method uses UTF-8 encoding without a Byte-Order Mark (BOM), so using the method will return an empty byte array. If it is necessary to include a UTF-8 identifier, such as a byte order mark, at the beginning of a file, use the method. is . @@ -7880,22 +7905,30 @@ It is not possible to change the compression status of a o To be added. - is . + or is . + is empty. - - is . The specified path, file name, or both exceed the system-defined maximum length. The specified path is invalid (for example, it is on an unmapped drive). An I/O error occurred while opening the file. - specified a file that is read-only. - - specified a file that is hidden. - - specified a directory. - This operation is not supported on the current platform. - The caller does not have the required permission. + + specified a file that is read-only. + + -or- + + specified a file that is hidden. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. + -or- + This operation is not supported on the current platform. + is in an invalid format. From d6aa03a1eae568ca194ff7895c66ae278e6a5164 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20S=C3=A1nchez=20L=C3=B3pez?= <1175054+carlossanlop@users.noreply.github.com> Date: Mon, 12 Aug 2024 11:49:00 -0700 Subject: [PATCH 4/4] Remove parentheses from System.Text.Encoding.GetPreamble --- xml/System.IO/File.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.IO/File.xml b/xml/System.IO/File.xml index 21baaf2a5ac..1f89926ed5c 100644 --- a/xml/System.IO/File.xml +++ b/xml/System.IO/File.xml @@ -7726,7 +7726,7 @@ It is not possible to change the compression status of a o Creates a new file, writes the specified string to the file, and then closes the file. If the target file already exists, it is truncated and overwritten. - This method uses UTF-8 encoding without a Byte-Order Mark (BOM), so using the method will return an empty byte array. If it is necessary to include a UTF-8 identifier, such as a byte order mark, at the beginning of a file, use the method. + This method uses UTF-8 encoding without a Byte-Order Mark (BOM), so using the method will return an empty byte array. If it is necessary to include a UTF-8 identifier, such as a byte order mark, at the beginning of a file, use the method. is .