Port new triple slash docs for .NET 7 (mostly EII) (dotnet#7424)

Co-authored-by: Genevieve Warren <[email protected]>

* System
* System.Activities
* System.ComponentModel
* System.Device
* System.Dynamic
* System.IdentityModel
* System.IO.Compression
* System.Messaging
* System.Numerics
* System.Resources
* System.Runtime.Intrinsics
* System.Security.Cryptography
* System.Speech
* System.Text.Json
* System.Transactions
* System.Web
* System.Workflow
* Microsoft.Extensions.Configuration
* Microsoft.Extension.Primitives
* Microsoft.Build.Construction
* Microsoft.Build.Framework
* Microsoft.Build.Globbing
* Microsoft.Build.Graph
* Microsoft.Build.Logging
* Microsoft.Build.Tasks

Author: carlossanlop

xml/Microsoft.Build.Construction/ProjectElement.xml

@@ -25,7 +25,7 @@
   </Interfaces>
   <Docs>
     <summary>
-            Abstract base class for MSBuild construction object model elements. 
+            Abstract base class for MSBuild construction object model elements.
             </summary>
     <remarks>To be added.</remarks>
   </Docs>
@@ -153,22 +153,22 @@
       </ReturnValue>
       <Docs>
         <summary>
-            Gets or sets the Condition value. 
-            It will return empty string IFF a condition attribute is legal but it’s not present or has no value. 
+            Gets or sets the Condition value.
+            It will return empty string IFF a condition attribute is legal but it’s not present or has no value.
             It will return null IFF a Condition attribute is illegal on that element.
             Removes the attribute if the value to set is empty.
             It is possible for derived classes to throw an <see cref="T:System.InvalidOperationException" /> if setting the condition is
             not applicable for those elements.
             </summary>
         <value>The Condition attribute value, or an empty string if the attribute is not present.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- Removes the Condition attribute if the value to set is set to null or an empty string. If the Condition attribute is not present, returns an empty string instead of throwing an exception because a nonexistent condition is implicitly true  
-  
- For the "ProjectExtensions" element, the getter returns null and the setter throws an exception for any value.  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+ Removes the Condition attribute if the value to set is set to null or an empty string. If the Condition attribute is not present, returns an empty string instead of throwing an exception because a nonexistent condition is implicitly true
+
+ For the "ProjectExtensions" element, the getter returns null and the setter throws an exception for any value.
+
  ]]></format>
         </remarks>
         <example> For the "ProjectExtensions" element, the getter returns null and the setter
@@ -320,7 +320,7 @@
         <ReturnType>System.String</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets the name of the associated element.  Useful for display in some circumstances.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
         <inheritdoc />
@@ -354,17 +354,17 @@
       </ReturnValue>
       <Docs>
         <summary>
-            Gets or sets the Label value. 
+            Gets or sets the Label value.
             Returns empty string if it is not present.
             Removes the attribute if the value to set is empty.
             </summary>
         <value>The label, or an empty string if no label is present.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- Removes the attribute if the value to set is empty.  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+ Removes the attribute if the value to set is empty.
+
  ]]></format>
         </remarks>
       </Docs>
@@ -413,7 +413,7 @@
       <Docs>
         <summary>
             Location of the corresponding Xml element.
-            May not be correct if file is not saved, or 
+            May not be correct if file is not saved, or
             file has been edited since it was last saved.
             In the case of an unsaved edit, the location only
             contains the path to the file that the element originates from.
@@ -486,7 +486,7 @@
         <ReturnType>System.String</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The outer markup associated with this project element.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
         <inheritdoc />
@@ -594,9 +594,7 @@
       </Parameters>
       <Docs>
         <param name="attribute">To be added.</param>
-        <summary>
-            Hook for subclasses to specify whether the given <param name="attribute" /> should be cloned or not
-            </summary>
+        <summary>Hook for subclasses to specify whether the given <paramref name="attribute" /> should be cloned or not.</summary>
         <returns>To be added.</returns>
         <remarks>To be added.</remarks>
       </Docs>

xml/Microsoft.Build.Framework/SdkReference.xml

@@ -79,9 +79,10 @@
         <Parameter Name="other" Type="Microsoft.Build.Framework.SdkReference" />
       </Parameters>
       <Docs>
-        <param name="other" />
-        <summary />
-        <returns />
+        <param name="other">An object to compare with this object.</param>
+        <summary>Indicates whether the current object is equal to another object of the same type.</summary>
+        <returns>
+          <see langword="true" /> if the current object is equal to the <paramref name="other" /> parameter; otherwise, <see langword="false" />.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>

xml/Microsoft.Build.Globbing/CompositeGlob.xml

@@ -122,10 +122,24 @@
         <Parameter Name="stringToMatch" Type="System.String" />
       </Parameters>
       <Docs>
-        <param name="stringToMatch">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="stringToMatch">The string to match. If the string represents a relative path, it will get normalized against the glob's root. Cannot be <see langword="null" />.</param>
+        <summary>Matches the given <paramref name="stringToMatch" /> against the glob.</summary>
+        <returns>
+          <see langword="false" /> if <paramref name="stringToMatch" /> contains invalid path or file characters; <see langword="true"/> otherwise.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Matching is path aware:
+
+- Slashes are normalized.
+- Arguments representing relative paths are normalized against the glob's root.
+
+For example, the glob `**/*.cs` does not match `../a.cs`, since `../a.cs` points outside of the glob root.
+
+          ]]></format>
+        </remarks>
         <inheritdoc />
       </Docs>
     </Member>

xml/Microsoft.Build.Globbing/MSBuildGlob.xml

@@ -126,10 +126,22 @@
         <Parameter Name="stringToMatch" Type="System.String" />
       </Parameters>
       <Docs>
-        <param name="stringToMatch">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="stringToMatch">The string to match. If the string represents a relative path, it will get normalized against the glob's root. Cannot be <see langword="null" />.</param>
+        <summary>Matches the given <paramref name="stringToMatch" /> against the glob.</summary>
+        <returns>
+          <see langword="false" /> if <paramref name="stringToMatch" /> contains invalid path or file characters; <see langword="true"/> otherwise.</returns>
+        <remarks><format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Matching is path aware:
+
+- Slashes are normalized.
+- Arguments representing relative paths are normalized against the glob's root.
+
+For example, the glob `**/*.cs` does not match `../a.cs`, since `../a.cs` points outside of the glob root.
+
+        ]]></format></remarks>
         <inheritdoc />
       </Docs>
     </Member>

xml/Microsoft.Build.Globbing/MSBuildGlobWithGaps.xml

@@ -146,10 +146,24 @@
         <Parameter Name="stringToMatch" Type="System.String" />
       </Parameters>
       <Docs>
-        <param name="stringToMatch">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="stringToMatch">The string to match. If the string represents a relative path, it will get normalized against the glob's root. Cannot be <see langword="null" />.</param>
+        <summary>Matches the given <paramref name="stringToMatch" /> against the glob.</summary>
+        <returns>
+            <see langword="false" /> if <paramref name="stringToMatch" /> contains invalid path or file characters; <see langword="true" /> otherwise.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Matching is path aware:
+
+- Slashes are normalized.
+- Arguments representing relative paths are normalized against the glob's root.
+
+For example, the glob `**/*.cs` does not match `../a.cs`, since `../a.cs` points outside of the glob root.
+
+          ]]></format>
+        </remarks>
         <inheritdoc />
       </Docs>
     </Member>

xml/Microsoft.Build.Graph/GraphBuildOptions.xml

@@ -148,9 +148,10 @@
         <Parameter Name="other" Type="Microsoft.Build.Graph.GraphBuildOptions" />
       </Parameters>
       <Docs>
-        <param name="other">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="other">An object to compare with this object.</param>
+        <summary>Indicates whether the current object is equal to another object of the same type.</summary>
+        <returns>
+          <see langword="true" /> if the current object is equal to the <paramref name="other" /> parameter; otherwise, <see langword="false" />.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>

xml/Microsoft.Build.Logging/BinaryLogger.xml

@@ -18,13 +18,7 @@
     </Interface>
   </Interfaces>
   <Docs>
-    <summary>
-            A logger that serializes all incoming BuildEventArgs in a compressed binary file (*.binlog). The file
-            can later be played back and piped into other loggers (file, console, etc) to reconstruct the log contents
-            as if a real build was happening. Additionally, this format can be read by tools for
-            analysis or visualization. Since the file format preserves structure, tools don't have to parse
-            text logs that erase a lot of useful information.
-            </summary>
+    <summary>A logger that serializes all incoming BuildEventArgs in a compressed binary file (*.binlog). The file can later be played back and piped into other loggers (file, console, etc) to reconstruct the log contents as if a real build was happening. Additionally, this format can be read by tools for analysis or visualization. Since the file format preserves structure, tools don't have to parse text logs that erase a lot of useful information.</summary>
     <remarks>The logger is public so that it can be instantiated from MSBuild.exe via command-line switch.</remarks>
   </Docs>
   <Members>
@@ -41,7 +35,7 @@
       </AssemblyInfo>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Initializes a new <see cref="T:Microsoft.Build.Logging.BinaryLogger"/> instance.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -61,9 +55,7 @@
         <ReturnType>Microsoft.Build.Logging.BinaryLogger+ProjectImportsCollectionMode</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>
-            Gets or sets whether to capture and embed project and target source files used during the build.
-            </summary>
+        <summary>Gets or sets whether to capture and embed project and target source files used during the build.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -90,10 +82,8 @@
         <Parameter Name="eventSource" Type="Microsoft.Build.Framework.IEventSource" />
       </Parameters>
       <Docs>
-        <param name="eventSource">To be added.</param>
-        <summary>
-            Initializes the logger by subscribing to events of IEventSource
-            </summary>
+        <param name="eventSource">The events available to loggers.</param>
+        <summary>Initializes the logger by subscribing to events of the specified event source.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -116,10 +106,8 @@
         <ReturnType>System.String</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>
-            The only supported parameter is the output log file path (e.g. "msbuild.binlog") 
-            </summary>
-        <value>To be added.</value>
+        <summary>Gets or sets the parameters. The only supported parameter is the output log file path (for example, "msbuild.binlog").</summary>
+        <value>The parameter string. Can be <see langword="null"/>.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -143,9 +131,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>
-            Closes the underlying file stream.
-            </summary>
+        <summary>Closes the underlying file stream.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -168,12 +154,9 @@
         <ReturnType>Microsoft.Build.Framework.LoggerVerbosity</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>
-            The binary logger Verbosity is always maximum (Diagnostic). It tries to capture as much
-            information as possible.
-            </summary>
-        <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <summary>Gets or sets the verbosity level.</summary>
+        <value>The verbosity level.</value>
+        <remarks>The binary logger Verbosity is always maximum (Diagnostic). It tries to capture as much information as possible.</remarks>
       </Docs>
     </Member>
   </Members>

xml/Microsoft.Build.Logging/BuildEventArgsReader.xml

@@ -18,9 +18,7 @@
     </Interface>
   </Interfaces>
   <Docs>
-    <summary>
-            Deserializes and returns BuildEventArgs-derived objects from a BinaryReader
-            </summary>
+    <summary>Deserializes and returns <see cref="T:Microsoft.Build.Framework.BuildEventArgs"/>-derived objects from a <see cref="T:System.IO.BinaryReader"/>.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -41,11 +39,9 @@
         <Parameter Name="fileFormatVersion" Type="System.Int32" />
       </Parameters>
       <Docs>
-        <param name="binaryReader">The BinaryReader to read BuildEventArgs from</param>
+        <param name="binaryReader">The <see cref="T:System.IO.BinaryReader"/> to read <see cref="T:Microsoft.Build.Framework.BuildEventArgs"/> from.</param>
         <param name="fileFormatVersion">The file format version of the log file being read.</param>
-        <summary>
-            Initializes a new instance of BuildEventArgsReader using a BinaryReader instance
-            </summary>
+        <summary>Initializes a new instance of <see cref="T:Microsoft.Build.Logging.BuildEventArgsReader"/> using a <see cref="T:System.IO.BinaryReader"/> instance.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -69,7 +65,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -90,10 +86,8 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>
-            Reads the next log record from the binary reader. If there are no more records, returns null.
-            </summary>
-        <returns>To be added.</returns>
+        <summary>Reads the next log record from the <see cref="T:System.IO.BinaryReader"/>.</summary>
+        <returns>The next <see cref="T:Microsoft.Build.Framework.BuildEventArgs"/>. If there are no more records, returns <see langword="null"/>.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>