Add XML documentation for 29 undocumented .NET 7.0 APIs (#117697)

* Initial plan

* Add documentation for System.Data.SqlTypes and System.Diagnostics APIs

Co-authored-by: jeffhandley <[email protected]>

* Add documentation for System.Reflection.Metadata, System.Runtime.Versioning, System.Security.Cryptography.Cose and System.Runtime.Serialization.Json APIs

Co-authored-by: jeffhandley <[email protected]>

* Add documentation for System.Security.Cryptography.X509Certificates.X509SubjectAlternativeNameExtension and System.Runtime.Serialization.DataContracts.DataContract APIs

Co-authored-by: jeffhandley <[email protected]>

* Use <see> tags and remove trailing whitespace

* Remove trailing whitespace

* Add missing <see> tag

* Revert to using <inheritdoc/> where it already existed

* Remove redundant X509SubjectAlternativeNameExtension documentation

Co-authored-by: PranavSenthilnathan <[email protected]>

* Update TraceConfiguration summary to reference TraceSource with proper XML doc tags

Co-authored-by: tarekgh <[email protected]>

* Apply XML documentation feedback: improve cref tags, fix whitespace, and restore X509SubjectAlternativeNameExtension docs

Co-authored-by: tarekgh <[email protected]>

* Apply feedback from code review: update FieldTypeEncoder.CustomModifiers documentation

Co-authored-by: tarekgh <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: jeffhandley <[email protected]>
Co-authored-by: Jeff Handley <[email protected]>
Co-authored-by: PranavSenthilnathan <[email protected]>
Co-authored-by: tarekgh <[email protected]>

Author: 4 people

src/libraries/System.Configuration.ConfigurationManager/src/System/Diagnostics/TraceConfiguration.cs

@@ -3,6 +3,9 @@
 
 namespace System.Diagnostics
 {
+    /// <summary>
+    /// Provides methods to register and configure tracing settings from configuration files to <see cref="TraceSource" /> and related classes.
+    /// </summary>
     public static class TraceConfiguration
     {
         private static volatile bool s_registered;

src/libraries/System.Data.Common/src/System/Data/SQLTypes/SQLBinary.cs

@@ -460,6 +460,11 @@ public static XmlQualifiedName GetXsdType(XmlSchemaSet schemaSet)
             return new XmlQualifiedName("base64Binary", XmlSchema.Namespace);
         }
 
+        /// <summary>
+        /// Wraps a byte array in a <see cref="SqlBinary" /> without copying the data.
+        /// </summary>
+        /// <param name="bytes">The byte array to wrap.</param>
+        /// <returns>A <see cref="SqlBinary" /> that wraps the provided byte array.</returns>
         public static SqlBinary WrapBytes(byte[] bytes)
         {
             return new SqlBinary(bytes, copy: false);

src/libraries/System.Data.Common/src/System/Data/SQLTypes/SQLDecimal.cs

@@ -1154,6 +1154,13 @@ private decimal ToDecimal()
             }
         }
 
+        /// <summary>
+        /// Writes the TDS (Tabular Data Stream) representation of this <see cref="SqlDecimal" /> to the specified destination.
+        /// </summary>
+        /// <param name="destination">The destination span to write the TDS (Tabular Data Stream) value to. Must be at least 4 elements long.</param>
+        /// <returns>The number of <see langword="uint" /> values written to the destination.</returns>
+        /// <exception cref="SqlNullValueException">Thrown when the <see cref="SqlDecimal" /> is <see langword="null" />.</exception>
+        /// <exception cref="ArgumentOutOfRangeException">Thrown when the destination span is too small.</exception>
         [CLSCompliant(false)]
         public int WriteTdsValue(Span<uint> destination)
         {

src/libraries/System.Data.Common/src/System/Data/SQLTypes/SQLMoney.cs

@@ -208,6 +208,11 @@ public override string ToString()
             return money.ToString("#0.00##", null);
         }
 
+        /// <summary>
+        /// Gets the TDS (Tabular Data Stream) representation of this <see cref="SqlMoney" /> value.
+        /// </summary>
+        /// <returns>A long value representing the TDS (Tabular Data Stream) representation.</returns>
+        /// <exception cref="SqlNullValueException">Thrown when the <see cref="SqlMoney" /> is <see langword="null" />.</exception>
         public long GetTdsValue()
         {
             if (IsNull)
@@ -249,6 +254,11 @@ public static SqlMoney Parse(string s)
             return money;
         }
 
+        /// <summary>
+        /// Creates a <see cref="SqlMoney" /> from a TDS (Tabular Data Stream) value.
+        /// </summary>
+        /// <param name="value">The TDS value to convert to <see cref="SqlMoney" />.</param>
+        /// <returns>A <see cref="SqlMoney" /> representing the TDS value.</returns>
         public static SqlMoney FromTdsValue(long value)
         {
             return new SqlMoney(value, 0);

src/libraries/System.Diagnostics.TraceSource/src/System/Diagnostics/InitializingSwitchEventArgs.cs

@@ -8,11 +8,18 @@ namespace System.Diagnostics
     /// </summary>
     public sealed class InitializingSwitchEventArgs : EventArgs
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="InitializingSwitchEventArgs"/> class.
+        /// </summary>
+        /// <param name="switch">The switch that is being initialized.</param>
         public InitializingSwitchEventArgs(Switch @switch)
         {
             Switch = @switch;
         }
 
+        /// <summary>
+        /// Gets the <see cref="Switch" /> that is being initialized.
+        /// </summary>
         public Switch Switch { get; }
     }
 }

src/libraries/System.Diagnostics.TraceSource/src/System/Diagnostics/InitializingTraceSourceEventArgs.cs

@@ -8,12 +8,23 @@ namespace System.Diagnostics
     /// </summary>
     public sealed class InitializingTraceSourceEventArgs : EventArgs
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="InitializingTraceSourceEventArgs"/> class.
+        /// </summary>
+        /// <param name="traceSource">The trace source that is being initialized.</param>
         public InitializingTraceSourceEventArgs(TraceSource traceSource)
         {
             TraceSource = traceSource;
         }
 
+        /// <summary>
+        /// Gets the trace source that is being initialized.
+        /// </summary>
         public TraceSource TraceSource { get; }
+
+        /// <summary>
+        /// Gets or sets a value indicating whether the trace source was initialized from configuration.
+        /// </summary>
         public bool WasInitialized { get; set; }
     }
 }

src/libraries/System.Private.CoreLib/src/System/Runtime/Versioning/PlatformAttributes.cs

@@ -134,14 +134,32 @@ public UnsupportedOSPlatformAttribute(string platformName, string? message) : ba
 #endif
         sealed class ObsoletedOSPlatformAttribute : OSPlatformAttribute
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ObsoletedOSPlatformAttribute"/> class with the specified platform name.
+        /// </summary>
+        /// <param name="platformName">The name of the platform where the API was obsoleted.</param>
         public ObsoletedOSPlatformAttribute(string platformName) : base(platformName)
         {
         }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ObsoletedOSPlatformAttribute"/> class with the specified platform name and message.
+        /// </summary>
+        /// <param name="platformName">The name of the platform where the API was obsoleted.</param>
+        /// <param name="message">The message that explains the obsolescence.</param>
         public ObsoletedOSPlatformAttribute(string platformName, string? message) : base(platformName)
         {
             Message = message;
         }
+
+        /// <summary>
+        /// Gets the message that explains the obsolescence.
+        /// </summary>
         public string? Message { get; }
+
+        /// <summary>
+        /// Gets or sets the URL that provides more information about the obsolescence.
+        /// </summary>
         public string? Url { get; set; }
     }
 

src/libraries/System.Private.DataContractSerialization/src/System/Runtime/Serialization/DataContract.cs

@@ -21,6 +21,9 @@
 
 namespace System.Runtime.Serialization.DataContracts
 {
+    /// <summary>
+    /// Represents a data contract that defines serialization and deserialization behavior for types.
+    /// </summary>
     public abstract class DataContract
     {
         internal const string SerializerTrimmerWarning = "Data Contract Serialization and Deserialization might require types that cannot be statically analyzed. Make sure all of the " +
@@ -46,6 +49,9 @@ internal DataContract(DataContractCriticalHelper helper)
             _ns = helper.Namespace;
         }
 
+        /// <summary>
+        /// Gets the contract type name for this data contract.
+        /// </summary>
         public virtual string? ContractType => null;
 
         internal MethodInfo? ParseMethod => _helper.ParseMethod;
@@ -190,24 +196,36 @@ internal virtual object ReadXmlElement(XmlReaderDelegator xmlReader, XmlObjectSe
             throw new InvalidDataContractException(SR.Format(SR.UnexpectedContractType, DataContract.GetClrTypeFullName(GetType()), DataContract.GetClrTypeFullName(UnderlyingType)));
         }
 
+        /// <summary>
+        /// Gets a value indicating whether the data contract represents a value type.
+        /// </summary>
         public virtual bool IsValueType
         {
             get => _helper.IsValueType;
             internal set => _helper.IsValueType = value;
         }
 
+        /// <summary>
+        /// Gets a value indicating whether the data contract is serialized by reference.
+        /// </summary>
         public virtual bool IsReference
         {
             get => _helper.IsReference;
             internal set => _helper.IsReference = value;
         }
 
+        /// <summary>
+        /// Gets the XML qualified name for the data contract.
+        /// </summary>
         public virtual XmlQualifiedName XmlName
         {
             get => _helper.XmlName;
             internal set => _helper.XmlName = value;
         }
 
+        /// <summary>
+        /// Gets the base data contract for this data contract.
+        /// </summary>
         public virtual DataContract? BaseContract
         {
             [RequiresDynamicCode(DataContract.SerializerAOTWarning)]

src/libraries/System.Private.DataContractSerialization/src/System/Runtime/Serialization/Json/DataContractJsonSerializer.cs

@@ -206,11 +206,20 @@ private XmlDictionaryString RootName
         // These Get/Set methods mirror the extensions that were added to DCS in the early days of Core, which allowed
         // using a slimmed-down surrogate on both NetFx and Core via type-forwarding mechanisms. That's why these are
         // a pair of methods instead of making the property itself public.
+
+        /// <summary>
+        /// Gets the current serialization surrogate provider.
+        /// </summary>
+        /// <returns>The current <see cref="ISerializationSurrogateProvider"/> instance, or <see langword="null"/> if no provider is set.</returns>
         public ISerializationSurrogateProvider? GetSerializationSurrogateProvider()
         {
             return SerializationSurrogateProvider;
         }
 
+        /// <summary>
+        /// Sets the serialization surrogate provider.
+        /// </summary>
+        /// <param name="provider">The <see cref="ISerializationSurrogateProvider"/> to use for serialization, or <see langword="null"/> to remove the current provider.</param>
         public void SetSerializationSurrogateProvider(ISerializationSurrogateProvider? provider)
         {
             SerializationSurrogateProvider = provider;

src/libraries/System.Reflection.Metadata/src/System/Reflection/Metadata/Ecma335/Encoding/BlobEncoders.cs

@@ -424,6 +424,10 @@ public FieldTypeEncoder(BlobBuilder builder)
             Builder = builder;
         }
 
+        /// <summary>
+        /// Creates <see cref="CustomModifiersEncoder" /> object that can be used to encode custom modifiers.
+        /// </summary>
+        /// <returns>A <see cref="CustomModifiersEncoder"/> instance that can be used to encode custom modifiers.</returns>
         public CustomModifiersEncoder CustomModifiers()
         {
             return new CustomModifiersEncoder(Builder);