Merge main into live

README.md

@@ -1,6 +1,8 @@
 # .NET API Reference Docs
 
-This repository contains documentation for the .NET API reference. We track all work for this repository using [GitHub issues](https://github.com/dotnet/dotnet-api-docs/issues). The documentation for APIs is built from the text and code snippets in this repo, and from the samples in the [dotnet/samples](https://github.com/dotnet/samples) repository.
+This repository contains documentation for the .NET API reference for .NET 8+ and package-provided APIs. We track all work for this repository using [GitHub issues](https://github.com/dotnet/dotnet-api-docs/issues). The documentation for APIs is built from the text and code snippets in this repo, and from the samples in the [dotnet/samples](https://github.com/dotnet/samples) repository.
+
+For .NET Framework API reference, see the [dotnet/dotnetfw-api-docs](https://github.com/dotnet/dotnetfw-api-docs) repository.
 
 The repository for conceptual .NET documentation is the [dotnet/docs repository](https://github.com/dotnet/docs).
 

xml/System.Runtime.Serialization/ISerializable.xml

@@ -48,12 +48,12 @@
   </TypeForwardingChain>
   <Interfaces />
   <Docs>
-    <summary>Allows an object to control its own serialization and deserialization through binary and XML serialization.</summary>
+    <summary>Allows an object to control its own serialization and deserialization during formatter-based (binary and SOAP) serialization.</summary>
     <remarks>
       <format type="text/markdown"><![CDATA[
 
 ## Remarks
- Any class that might be serialized using binary or XML serialization must be marked with the <xref:System.SerializableAttribute>. If a class needs to control its binary or XML serialization process, it can implement the <xref:System.Runtime.Serialization.ISerializable> interface. The <xref:System.Runtime.Serialization.Formatter> calls the <xref:System.Runtime.Serialization.ISerializable.GetObjectData*> at serialization time and populates the supplied <xref:System.Runtime.Serialization.SerializationInfo> with all the data required to represent the object. The <xref:System.Runtime.Serialization.Formatter> creates a <xref:System.Runtime.Serialization.SerializationInfo> with the type of the object in the graph. Objects that need to send proxies for themselves can use the <xref:System.Runtime.Serialization.SerializationInfo.FullTypeName*> and <xref:System.Runtime.Serialization.SerializationInfo.AssemblyName*> methods on <xref:System.Runtime.Serialization.SerializationInfo> to change the transmitted information.
+ Any class that might be serialized by a formatter, such as <xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter> or `SoapFormatter`, must be marked with the <xref:System.SerializableAttribute>. If a class needs to control this formatter-based serialization process, it can implement the <xref:System.Runtime.Serialization.ISerializable> interface. The <xref:System.Runtime.Serialization.Formatter> calls the <xref:System.Runtime.Serialization.ISerializable.GetObjectData*> at serialization time and populates the supplied <xref:System.Runtime.Serialization.SerializationInfo> with all the data required to represent the object. The <xref:System.Runtime.Serialization.Formatter> creates a <xref:System.Runtime.Serialization.SerializationInfo> with the type of the object in the graph. Objects that need to send proxies for themselves can use the <xref:System.Runtime.Serialization.SerializationInfo.FullTypeName*> and <xref:System.Runtime.Serialization.SerializationInfo.AssemblyName*> methods on <xref:System.Runtime.Serialization.SerializationInfo> to change the transmitted information.
 
  In the case of class inheritance, it is possible to serialize a class that derives from a base class that implements <xref:System.Runtime.Serialization.ISerializable>. In this case, the derived class should call the base class implementation of <xref:System.Runtime.Serialization.ISerializable.GetObjectData*> inside its implementation of <xref:System.Runtime.Serialization.ISerializable.GetObjectData*>. Otherwise, the data from the base class will not be serialized.
 
@@ -69,6 +69,9 @@
 
  For more information about serialization of classes that extend <xref:System.MarshalByRefObject>, see <xref:System.Runtime.Remoting.Messaging.RemotingSurrogateSelector>. For more information about implementing <xref:System.Runtime.Serialization.ISerializable>, see [Custom Serialization](/dotnet/standard/serialization/custom-serialization).
 
+> [!IMPORTANT]
+> This interface applies only to formatter-based serialization, such as with <xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter> and `SoapFormatter`. Here, *XML serialization* refers to the SOAP format produced by `SoapFormatter`, not to <xref:System.Xml.Serialization.XmlSerializer>. <xref:System.Xml.Serialization.XmlSerializer> ignores <xref:System.Runtime.Serialization.ISerializable>. To control how a type is serialized by <xref:System.Xml.Serialization.XmlSerializer>, implement <xref:System.Xml.Serialization.IXmlSerializable> instead.
+
 > [!NOTE]
 > This interface does not apply to JSON serialization using <xref:System.Text.Json?displayProperty=fullName>.
 
@@ -77,6 +80,7 @@
     <block subset="none" type="overrides">
       <para>Implement this interface to allow an object to take part in its own serialization and deserialization.</para>
     </block>
+    <altmember cref="T:System.Xml.Serialization.IXmlSerializable" />
     <related type="Article" href="/dotnet/standard/serialization/xml-and-soap-serialization">XML and SOAP Serialization</related>
     <related type="Article" href="/dotnet/standard/serialization/custom-serialization">Custom serialization</related>
   </Docs>

xml/System/BinaryData.xml

@@ -1290,9 +1290,9 @@ No special treatment is given to the contents of the data. It is merely decoded
         </Parameter>
       </Parameters>
       <Docs>
-        <param name="mediaType">To be added.</param>
+        <param name="mediaType">The MIME type of this data, for example, <see cref="F:System.Net.Mime.MediaTypeNames.Application.Octet" />.</param>
         <summary>
-          <para>Creates a <see cref="T:System.BinaryData" /> instance by wrapping the same data and changed <see cref="P:System.BinaryData.MediaType" /> to <see pref="mediaType" /> value.</para>
+          <para>Creates a <see cref="T:System.BinaryData" /> instance by wrapping the same data and changing the <see cref="P:System.BinaryData.MediaType" /> to <paramref name="mediaType" />.</para>
         </summary>
         <returns>A wrapper over the same data with specified <see cref="P:System.BinaryData.MediaType" />.</returns>
         <remarks>To be added.</remarks>

xml/System/Boolean.xml

@@ -1586,11 +1586,12 @@ This member is an explicit interface member implementation. It can be used only
         <Parameter Name="result" Type="System.Boolean" RefType="out" />
       </Parameters>
       <Docs>
-        <param name="s">To be added.</param>
-        <param name="provider">To be added.</param>
-        <param name="result">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="s">The string to parse.</param>
+        <param name="provider">An object that provides culture-specific formatting information about <paramref name="s" />.</param>
+        <param name="result">When this method returns, contains the result of successfully parsing <paramref name="s" />, or an undefined value on failure.</param>
+        <summary>Tries to parse a string into a value.</summary>
+        <returns>
+          <see langword="true" /> if <paramref name="s" /> was successfully parsed; otherwise, <see langword="false" />.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -1657,11 +1658,12 @@ This member is an explicit interface member implementation. It can be used only
         <Parameter Name="result" Type="System.Boolean" RefType="out" />
       </Parameters>
       <Docs>
-        <param name="s">To be added.</param>
-        <param name="provider">To be added.</param>
-        <param name="result">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="s">The span of characters to parse.</param>
+        <param name="provider">An object that provides culture-specific formatting information about <paramref name="s" />.</param>
+        <param name="result">When this method returns, contains the result of successfully parsing <paramref name="s" />, or an undefined value on failure.</param>
+        <summary>Tries to parse a span of characters into a value.</summary>
+        <returns>
+          <see langword="true" /> if <paramref name="s" /> was successfully parsed; otherwise, <see langword="false" />.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>

xml/System/ConsoleKey.xml

@@ -3005,7 +3005,7 @@
       </ReturnValue>
       <MemberValue>0</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>No key was pressed.</summary>
       </Docs>
     </Member>
     <Member MemberName="NumPad0">

xml/System/ConsoleModifiers.xml

@@ -159,7 +159,7 @@
       </ReturnValue>
       <MemberValue>0</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>No modifier key.</summary>
       </Docs>
     </Member>
     <Member MemberName="Shift">

xml/System/DateTimeOffset.xml

@@ -5857,7 +5857,7 @@ Me.ToUtcDateTime().ToFileTime()
         <param name="utf8Destination">The span in which to write this instance's value formatted as a span of bytes.</param>
         <param name="bytesWritten">When this method returns, contains the number of bytes that were written in <paramref name="utf8Destination" />.</param>
         <param name="format">A span containing the characters that represent a standard or custom format string that defines the acceptable format for <paramref name="utf8Destination" />.</param>
-        <param name="formatProvider">To be added.</param>
+        <param name="formatProvider">An optional object that supplies culture-specific formatting information for <paramref name="utf8Destination" />.</param>
         <summary>Tries to format the value of the current instance as UTF-8 into the provided span of bytes.</summary>
         <returns>
           <see langword="true" /> if the formatting was successful; otherwise, <see langword="false" />.</returns>

xml/System/Enum.xml

@@ -3493,8 +3493,8 @@ The following example demonstrates using an enumeration to represent named value
         </Parameter>
       </Parameters>
       <Docs>
-        <typeparam name="TEnum">To be added.</typeparam>
-        <param name="value">To be added.</param>
+        <typeparam name="TEnum">The type of the enumeration.</typeparam>
+        <param name="value">The enumeration value to format.</param>
         <param name="destination">The span into which to write the instance's value formatted as a span of characters.</param>
         <param name="charsWritten">When this method returns, contains the number of characters that were written in <paramref name="destination" />.</param>
         <param name="format">A span containing the character that represents the standard format string that defines the acceptable format of destination. This value can be empty, or "g", "d", "f", or "x".</param>

xml/System/Guid.xml

@@ -289,10 +289,13 @@
         <Parameter Name="bigEndian" Type="System.Boolean" />
       </Parameters>
       <Docs>
-        <param name="b">To be added.</param>
-        <param name="bigEndian">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="b">A 16-element read-only span containing the bytes with which to initialize the GUID.</param>
+        <param name="bigEndian">
+          <see langword="true" /> to interpret <paramref name="b" /> as big-endian; <see langword="false" /> to interpret it as little-endian.</param>
+        <summary>Initializes a new instance of the <see cref="T:System.Guid" /> structure by using the value represented by the specified read-only span of bytes and the specified endianness.</summary>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentException">
+          <paramref name="b" /> is not 16 bytes long.</exception>
       </Docs>
     </Member>
     <Member MemberName=".ctor">
@@ -1888,9 +1891,10 @@ The <xref:System.Guid.ParseExact*> method requires the read-only character span
         <Parameter Name="bigEndian" Type="System.Boolean" />
       </Parameters>
       <Docs>
-        <param name="bigEndian">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="bigEndian">
+          <see langword="true" /> to write the bytes in big-endian byte order; <see langword="false" /> to write them in little-endian byte order.</param>
+        <summary>Returns a 16-element byte array that contains the value of this instance, using the specified endianness.</summary>
+        <returns>A 16-element byte array.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -2134,11 +2138,12 @@ The <xref:System.Guid.ParseExact*> method requires the read-only character span
         </Parameter>
       </Parameters>
       <Docs>
-        <param name="utf8Destination">To be added.</param>
-        <param name="bytesWritten">To be added.</param>
-        <param name="format">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="utf8Destination">The span in which to write the GUID as a span of UTF-8 bytes.</param>
+        <param name="bytesWritten">When this method returns, contains the number of bytes written into <paramref name="utf8Destination" />.</param>
+        <param name="format">A read-only span containing the character representing one of the following specifiers that indicates the exact format to use when interpreting the current GUID instance: "N", "D", "B", "P", or "X".</param>
+        <summary>Tries to format the current GUID instance as UTF-8 into the provided span of bytes.</summary>
+        <returns>
+          <see langword="true" /> if the formatting operation was successful; <see langword="false" /> otherwise.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -2656,11 +2661,13 @@ The <xref:System.Guid.ParseExact*> method requires the read-only character span
         <Parameter Name="bytesWritten" Type="System.Int32" RefType="out" />
       </Parameters>
       <Docs>
-        <param name="destination">To be added.</param>
-        <param name="bigEndian">To be added.</param>
-        <param name="bytesWritten">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="destination">The span in which to write the GUID as a span of bytes.</param>
+        <param name="bigEndian">
+          <see langword="true" /> to write the bytes in big-endian byte order; <see langword="false" /> to write them in little-endian byte order.</param>
+        <param name="bytesWritten">When this method returns, contains the number of bytes written into <paramref name="destination" />.</param>
+        <summary>Tries to write the current GUID instance into a span of bytes, using the specified endianness.</summary>
+        <returns>
+          <see langword="true" /> if the GUID is successfully written to the specified span; <see langword="false" /> otherwise.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>