Add some xml comments (#88433)

src/libraries/System.Collections.Specialized/src/System/Collections/Specialized/ListDictionary.cs

@@ -5,13 +5,10 @@
 
 namespace System.Collections.Specialized
 {
-    /// <devdoc>
-    ///  <para>
-    ///    This is a simple implementation of IDictionary using a singly linked list. This
-    ///    will be smaller and faster than a Hashtable if the number of elements is 10 or less.
-    ///    This should not be used if performance is important for large numbers of elements.
-    ///  </para>
-    /// </devdoc>
+    /// <summary>
+    /// Implements <see cref="IDictionary"/> using a singly linked list.
+    /// Recommended for collections that typically include fewer than 10 items.
+    /// </summary>
     [Serializable]
     [System.Runtime.CompilerServices.TypeForwardedFrom("System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089")]
     public class ListDictionary : IDictionary

src/libraries/System.Private.CoreLib/src/Internal/AssemblyAttributes.cs

@@ -1,15 +1,6 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
-/*============================================================
-**
-** This file exists to contain miscellaneous module-level attributes
-** and other miscellaneous stuff.
-**
-**
-**
-===========================================================*/
-
 using System;
 using System.Reflection;
 using System.Runtime.InteropServices;

src/libraries/System.Private.CoreLib/src/System/AccessViolationException.cs

@@ -1,21 +1,15 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
-/*=============================================================================
-**
-**
-**
-** Purpose: Exception class representing an AV that was deemed unsafe and may have corrupted the application.
-**
-**
-=============================================================================*/
-
 using System.ComponentModel;
 using System.Runtime.CompilerServices;
 using System.Runtime.Serialization;
 
 namespace System
 {
+    /// <summary>
+    /// The exception that is thrown when there is an attempt to read or write protected memory.
+    /// </summary>
     [Serializable]
     [TypeForwardedFrom("mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089")]
     public class AccessViolationException : SystemException

src/libraries/System.Private.CoreLib/src/System/ApplicationException.cs

@@ -1,28 +1,20 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
-/*=============================================================================
-**
-**
-**
-** Purpose: The base class for all "less serious" exceptions that must be
-**          declared or caught.
-**
-**
-=============================================================================*/
-
 using System.ComponentModel;
 using System.Runtime.CompilerServices;
 using System.Runtime.Serialization;
 
 namespace System
 {
-    // The ApplicationException is the base class for nonfatal,
-    // application errors that occur.  These exceptions are generated
-    // (i.e., thrown) by an application, not the Runtime. Applications that need
-    // to create their own exceptions do so by extending this class.
-    // ApplicationException extends but adds no new functionality to
-    // RecoverableException.
+    /// <summary>
+    /// Serves as the base class for application-defined exceptions.
+    /// </summary>
+    /// <remarks>
+    /// You should derive custom exceptions from the <see cref="Exception" /> class rather than the <see cref="ApplicationException" /> class.
+    /// You should not throw an <see cref="ApplicationException" /> in your code, and you should not catch an <see cref="ApplicationException" />
+    /// unless you intend to re-throw the original exception.
+    /// </remarks>
     [Serializable]
     [TypeForwardedFrom("mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089")]
     public class ApplicationException : Exception

src/libraries/System.Private.CoreLib/src/System/ArgumentException.cs

@@ -1,25 +1,16 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
-/*=============================================================================
-**
-**
-**
-** Purpose: Exception class for invalid arguments to a method.
-**
-**
-=============================================================================*/
-
 using System.ComponentModel;
 using System.Diagnostics.CodeAnalysis;
 using System.Runtime.CompilerServices;
 using System.Runtime.Serialization;
 
 namespace System
 {
-    // The ArgumentException is thrown when an argument does not meet
-    // the contract of the method.  Ideally it should give a meaningful error
-    // message describing what was wrong and which parameter is incorrect.
+    /// <summary>
+    /// The exception that is thrown when one of the arguments provided to a method is not valid.
+    /// </summary>
     [Serializable]
     [TypeForwardedFrom("mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089")]
     public class ArgumentException : SystemException

src/libraries/System.Private.CoreLib/src/System/ArgumentNullException.cs

@@ -1,24 +1,16 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
-/*=============================================================================
-**
-**
-**
-** Purpose: Exception class for null arguments to a method.
-**
-**
-=============================================================================*/
-
 using System.ComponentModel;
 using System.Diagnostics.CodeAnalysis;
 using System.Runtime.CompilerServices;
 using System.Runtime.Serialization;
 
 namespace System
 {
-    // The ArgumentException is thrown when an argument
-    // is null when it shouldn't be.
+    /// <summary>
+    /// The exception that is thrown when a <see langword="null"/> reference (<see langword="Nothing"/> in Visual Basic) is passed to a method that does not accept it as a valid argument.
+    /// </summary>
     [Serializable]
     [TypeForwardedFrom("mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089")]
     public class ArgumentNullException : ArgumentException

src/libraries/System.Private.CoreLib/src/System/ArgumentOutOfRangeException.cs

@@ -1,15 +1,6 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
-/*=============================================================================
-**
-**
-**
-** Purpose: Exception class for method arguments outside of the legal range.
-**
-**
-=============================================================================*/
-
 using System.ComponentModel;
 using System.Runtime.Serialization;
 using System.Runtime.CompilerServices;
@@ -19,8 +10,9 @@
 
 namespace System
 {
-    // The ArgumentOutOfRangeException is thrown when an argument
-    // is outside the legal range for that argument.
+    /// <summary>
+    /// The exception that is thrown when the value of an argument is outside the allowable range of values as defined by the invoked method.
+    /// </summary>
     [Serializable]
     [TypeForwardedFrom("mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089")]
     public class ArgumentOutOfRangeException : ArgumentException

src/libraries/System.Private.CoreLib/src/System/ArithmeticException.cs

@@ -1,23 +1,15 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
-/*=============================================================================
-**
-**
-**
-** Purpose: Exception class for bad arithmetic conditions!
-**
-**
-=============================================================================*/
-
 using System.ComponentModel;
 using System.Runtime.CompilerServices;
 using System.Runtime.Serialization;
 
 namespace System
 {
-    // The ArithmeticException is thrown when overflow or underflow
-    // occurs.
+    /// <summary>
+    /// The exception that is thrown for errors in an arithmetic, casting, or conversion operation.
+    /// </summary>
     [Serializable]
     [TypeForwardedFrom("mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089")]
     public class ArithmeticException : SystemException

src/libraries/System.Private.CoreLib/src/System/ArraySegment.cs

@@ -1,17 +1,6 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
-/*============================================================
-**
-**
-**
-** Purpose: Convenient wrapper for an array, an offset, and
-**          a count.  Ideally used in streams & collections.
-**          Net Classes will consume an array of these.
-**
-**
-===========================================================*/
-
 using System.Collections;
 using System.Collections.Generic;
 using System.Diagnostics;
@@ -20,6 +9,9 @@
 
 namespace System
 {
+    /// <summary>
+    /// Delimits a section of a one-dimensional array.
+    /// </summary>
     // Note: users should make sure they copy the fields out of an ArraySegment onto their stack
     // then validate that the fields describe valid bounds within the array.  This must be done
     // because assignments to value types are not atomic, and also because one thread reading

src/libraries/System.Private.CoreLib/src/System/ArrayTypeMismatchException.cs

@@ -1,23 +1,15 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
-/*=============================================================================
-**
-**
-**
-** Purpose: The arrays are of different primitive types.
-**
-**
-=============================================================================*/
-
 using System.ComponentModel;
 using System.Runtime.CompilerServices;
 using System.Runtime.Serialization;
 
 namespace System
 {
-    // The ArrayMismatchException is thrown when an attempt to store
-    // an object of the wrong type within an array occurs.
+    /// <summary>
+    /// The exception that is thrown when an attempt is made to store an element of the wrong type within an array.
+    /// </summary>
     [Serializable]
     [TypeForwardedFrom("mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089")]
     public class ArrayTypeMismatchException : SystemException

src/libraries/System.Private.CoreLib/src/System/AsyncCallback.cs

@@ -1,15 +1,10 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
-/*============================================================
-**
-** Interface: AsyncCallbackDelegate
-**
-** Purpose: Type of callback for async operations
-**
-===========================================================*/
-
 namespace System
 {
+    /// <summary>
+    /// References a method to be called when a corresponding asynchronous operation completes.
+    /// </summary>
     public delegate void AsyncCallback(IAsyncResult ar);
 }

src/libraries/System.Private.CoreLib/src/System/AttributeUsageAttribute.cs

@@ -1,18 +1,11 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
-/*============================================================
-**
-**
-**
-** Purpose: The class denotes how to specify the usage of an attribute
-**
-**
-===========================================================*/
-
 namespace System
 {
-    /* By default, attributes are inherited and multiple attributes are not allowed */
+    /// <summary>
+    /// Specifies the usage of another attribute class.
+    /// </summary>
     [AttributeUsage(AttributeTargets.Class, Inherited = true)]
     public sealed class AttributeUsageAttribute : Attribute
     {

src/libraries/System.Private.CoreLib/src/System/BadImageFormatException.cs

@@ -1,22 +1,16 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
-/*============================================================
-**
-**
-**
-** Purpose: Exception to an invalid dll or executable format.
-**
-**
-===========================================================*/
-
 using System.ComponentModel;
 using System.IO;
 using System.Runtime.CompilerServices;
 using System.Runtime.Serialization;
 
 namespace System
 {
+    /// <summary>
+    /// The exception that is thrown when the file image of an assembly or an executable program is invalid.
+    /// </summary>
     [Serializable]
     [TypeForwardedFrom("mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089")]
     public partial class BadImageFormatException : SystemException

src/libraries/System.Private.CoreLib/src/System/Boolean.cs

@@ -1,23 +1,16 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
-/*============================================================
-**
-**
-**
-** Purpose: The boolean class serves as a wrapper for the primitive
-** type boolean.
-**
-**
-===========================================================*/
-
 using System.Diagnostics.CodeAnalysis;
 using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
 using System.Runtime.Versioning;
 
 namespace System
 {
+    /// <summary>
+    /// Represents a boolean (<see langword="true"/> or <see langword="false"/>) value.
+    /// </summary>
     [Serializable]
     [TypeForwardedFrom("mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089")]
     public readonly struct Boolean

src/libraries/System.Private.CoreLib/src/System/CLSCompliantAttribute.cs

@@ -1,17 +1,11 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
-/*=============================================================================
-**
-**
-**
-** Purpose: Container for assemblies.
-**
-**
-=============================================================================*/
-
 namespace System
 {
+    /// <summary>
+    /// Indicates whether a program element is compliant with the Common Language Specification (CLS).
+    /// </summary>
     [AttributeUsage(AttributeTargets.All, Inherited = true, AllowMultiple = false)]
     public sealed class CLSCompliantAttribute : Attribute
     {