Small XML doc refreshing

src/TestFramework/TestFramework/Attributes/DataSource/DataSourceAttribute.cs

@@ -8,10 +8,18 @@ namespace Microsoft.VisualStudio.TestTools.UnitTesting;
 /// <summary>
 /// Specifies connection string, table name and row access method for data driven testing.
 /// </summary>
-/// <example>
+/// <remarks>
+/// <list type="bullet">
+/// <item>This works only on .NET Framework and is not supported on .NET Core or later.</item>
+/// <item>
+/// The following shows example usages for this attribute:
+/// <code>
 /// [DataSource("Provider=SQLOLEDB.1;Data Source=source;Integrated Security=SSPI;Initial Catalog=EqtCoverage;Persist Security Info=False", "MyTable")]
 /// [DataSource("dataSourceNameFromConfigFile")].
-/// </example>
+/// </code>
+/// </item>
+/// </list>
+/// </remarks>
 [SuppressMessage("Microsoft.Design", "CA1019:DefineAccessorsForAttributeArguments", Justification = "Compat")]
 [AttributeUsage(AttributeTargets.Method)]
 public sealed class DataSourceAttribute : Attribute

src/TestFramework/TestFramework/Attributes/DataSource/DataTestMethodAttribute.cs

@@ -4,7 +4,8 @@
 namespace Microsoft.VisualStudio.TestTools.UnitTesting;
 
 /// <summary>
-/// Attribute for data driven test where data can be specified in-line.
+/// This attribute doesn't currently provide any different functionality compared to <see cref="TestMethodAttribute"/>. It's only
+/// present for backward compatibility. Using <see cref="TestMethodAttribute"/> is recommended, even for parameterized tests.
 /// </summary>
 [AttributeUsage(AttributeTargets.Method)]
 public class DataTestMethodAttribute : TestMethodAttribute

src/TestFramework/TestFramework/Attributes/TestMethod/ExpectedExceptionAttribute.cs

@@ -8,6 +8,9 @@ namespace Microsoft.VisualStudio.TestTools.UnitTesting;
 /// <summary>
 /// Attribute that specifies to expect an exception of the specified type.
 /// </summary>
+/// <remarks>
+/// We recommend using one of the Assert.ThrowsException or Assert.ThrowsExceptionAsync overload instead of using this attribute.
+/// </remarks>
 [AttributeUsage(AttributeTargets.Method)]
 public sealed class ExpectedExceptionAttribute : ExpectedExceptionBaseAttribute
 {

src/TestFramework/TestFramework/Attributes/TestMethod/ExpectedExceptionBaseAttribute.cs

@@ -9,6 +9,9 @@ namespace Microsoft.VisualStudio.TestTools.UnitTesting;
 /// <summary>
 /// Base class for attributes that specify to expect an exception from a unit test.
 /// </summary>
+/// <remarks>
+/// We recommend using one of the Assert.ThrowsException or Assert.ThrowsExceptionAsync overload instead of using this attribute.
+/// </remarks>
 [AttributeUsage(AttributeTargets.Method)]
 public abstract class ExpectedExceptionBaseAttribute : Attribute
 {

src/TestFramework/TestFramework/Attributes/TestMethod/IgnoreAttribute.cs

@@ -4,13 +4,16 @@
 namespace Microsoft.VisualStudio.TestTools.UnitTesting;
 
 /// <summary>
-/// The ignore attribute.
+/// This attribute is used to ignore a test class or a test method, with an optional message.
 /// </summary>
+/// <remarks>
+/// This attribute isn't inherited. Applying it to a base class will not cause derived classes to be ignored.
+/// </remarks>
 [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, Inherited = false)]
 public sealed class IgnoreAttribute : Attribute
 {
     /// <summary>
-    /// Initializes a new instance of the <see cref="IgnoreAttribute"/> class.
+    /// Initializes a new instance of the <see cref="IgnoreAttribute"/> class with an empty message.
     /// </summary>
     public IgnoreAttribute()
         : this(string.Empty)
@@ -26,7 +29,7 @@ public IgnoreAttribute()
     public IgnoreAttribute(string? message) => IgnoreMessage = message;
 
     /// <summary>
-    /// Gets the owner.
+    /// Gets the ignore message indicating the reason for ignoring the test method or test class.
     /// </summary>
     public string? IgnoreMessage { get; }
 }

src/TestFramework/TestFramework/Attributes/TestMethod/TestClassAttribute.cs

@@ -4,8 +4,16 @@
 namespace Microsoft.VisualStudio.TestTools.UnitTesting;
 
 /// <summary>
-/// The test class attribute.
+/// This attribute is used to mark test classes.
 /// </summary>
+/// <remarks>
+/// Test classes must be:
+/// <list type="bullet">
+/// <item>public, or if <see cref="DiscoverInternalsAttribute"/> is used then it can be internal.</item>
+/// <item>not static</item>
+/// <item>not generic</item>
+/// </list>
+/// </remarks>
 [AttributeUsage(AttributeTargets.Class)]
 public class TestClassAttribute : Attribute
 {

src/TestFramework/TestFramework/Attributes/TestMethod/TestMethodAttribute.cs

@@ -3,9 +3,29 @@
 
 namespace Microsoft.VisualStudio.TestTools.UnitTesting;
 
+#pragma warning disable CS1574 // XML comment has cref attribute that could not be resolved - The warning is for ValueTask.
 /// <summary>
-/// The test method attribute.
+/// This attribute is used to mark test methods.
 /// </summary>
+/// <remarks>
+/// <list type="bullet">
+/// <item>
+/// When using other attributes like <see cref="DataRowAttribute" /> or <see cref="DynamicDataAttribute" />, it
+/// the use of <see cref="TestMethodAttribute" /> is still required.
+/// </item>
+/// <item>
+/// Test methods must be:
+/// <list type="bullet">
+/// <item>public, or if <see cref="DiscoverInternalsAttribute"/> is used then it can be internal.</item>
+/// <item>not static</item>
+/// <item>not generic</item>
+/// <item>not abstract</item>
+/// <item>return type is either <see langword="void"/>, <see cref="Task"/>, or <see cref="ValueTask"/>. If <see langword="void"/>, then it shouldn't be <see langword="async"/>.</item>
+/// </list>
+/// </item>
+/// </list>
+/// </remarks>
+#pragma warning restore CS1574 // XML comment has cref attribute that could not be resolved// XML comment has cref attribute that could not be resolved
 [AttributeUsage(AttributeTargets.Method)]
 public class TestMethodAttribute : Attribute
 {