Port doc comment changes from docs repo

src/Build/Definition/ProjectCollection.cs

@@ -432,7 +432,7 @@ public static ProjectCollection GlobalProjectCollection
         /// This is the Windows file version (specifically the value of the FileVersion
         /// resource), not necessarily the assembly version.
         /// If you want the assembly version, use Constants.AssemblyVersion.
-        /// This is not the <see cref="ToolsetsVersion">ToolsetCollectionVersion</see>.
+        /// This is not the <see cref="P:Microsoft.Build.BuildEngine.ToolsetCollection.ToolsVersions*">ToolsetCollection.ToolsVersions</see>.
         /// </remarks>
         public static Version Version
         {

src/Build/Logging/BinaryLogger/BinaryLogger.cs

@@ -89,19 +89,20 @@ public enum ProjectImportsCollectionMode
 
         private string FilePath { get; set; }
 
-        /// <summary>
+        /// <summary> Gets or sets the verbosity level.</summary>
+        /// <remarks>
         /// The binary logger Verbosity is always maximum (Diagnostic). It tries to capture as much
         /// information as possible.
-        /// </summary>
+        /// </remarks>
         public LoggerVerbosity Verbosity { get; set; } = LoggerVerbosity.Diagnostic;
 
         /// <summary>
-        /// The only supported parameter is the output log file path (e.g. "msbuild.binlog") 
+        /// Gets or sets the parameters. The only supported parameter is the output log file path (for example, "msbuild.binlog"). 
         /// </summary>
         public string Parameters { get; set; }
 
         /// <summary>
-        /// Initializes the logger by subscribing to events of IEventSource
+        /// Initializes the logger by subscribing to events of the specified event source.
         /// </summary>
         public void Initialize(IEventSource eventSource)
         {

src/Build/Logging/BinaryLogger/BuildEventArgsReader.cs

@@ -53,9 +53,9 @@ public class BuildEventArgsReader : IDisposable
             typeof(BuildEventArgs).GetField("senderName", BindingFlags.Instance | BindingFlags.NonPublic);
 
         /// <summary>
-        /// Initializes a new instance of BuildEventArgsReader using a BinaryReader instance
+        /// Initializes a new instance of <see cref="T:Microsoft.Build.Logging.BuildEventArgsReader"/> using a <see cref="T:System.IO.BinaryReader"/> instance.
         /// </summary>
-        /// <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>
         public BuildEventArgsReader(BinaryReader binaryReader, int fileFormatVersion)
         {
@@ -79,8 +79,11 @@ public void Dispose()
         internal event Action<BinaryLogRecordKind, byte[]> OnBlobRead;
 
         /// <summary>
-        /// Reads the next log record from the binary reader. If there are no more records, returns null.
+        /// 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>
         public BuildEventArgs Read()
         {
             BinaryLogRecordKind recordKind = (BinaryLogRecordKind)ReadInt32();

src/Build/Logging/ProfilerLogger.cs

@@ -51,12 +51,15 @@ internal static ProfilerLogger CreateForTesting()
         }
 
         /// <summary>
-        /// Verbosity is ignored by this logger
+        /// Gets or sets the verbosity level.
         /// </summary>
+        /// <remarks>
+        /// Verbosity is ignored by this logger.
+        /// </remarks>
         public LoggerVerbosity Verbosity { get; set; }
 
         /// <summary>
-        /// No specific parameters are used by this logger
+        /// No specific parameters are used by this logger.
         /// </summary>
         public string Parameters { get; set; }
 
@@ -74,7 +77,7 @@ public void Initialize(IEventSource eventSource)
         }
 
         /// <summary>
-        /// On shutdown, the profiler report is written to disk
+        /// On shutdown, the profiler report is written to disk.
         /// </summary>
         public void Shutdown()
         {
@@ -103,13 +106,13 @@ private void ProjectEvaluationFinishedRaised(object sender, BuildEventArgs e)
         }
 
         /// <summary>
-        /// Returns the result of aggregating all profiled projects across a build
+        /// Returns the result of aggregating all profiled projects across a build.
         /// </summary>
         /// <param name="pruneSmallItems">Whether small items should be pruned. This is called with false on some tests since the result may vary depending on the evaluator speed</param>
         /// <remarks>
         /// Not thread safe. After this method is called, the assumption is that no new ProjectEvaluationFinishedEventArgs will arrive.
         /// In the regular code path, this method is called only once per build. But some test cases may call it multiple times to validate 
-        /// the aggregated data
+        /// the aggregated data.
         /// </remarks>
         internal ProfilerResult GetAggregatedResult(bool pruneSmallItems = true)
         {
@@ -230,7 +233,7 @@ private static Dictionary<EvaluationLocation, ProfiledLocation> PruneSmallItems(
         }
 
         /// <summary>
-        /// Finds the first ancestor of parentId (which could be itself) that is either an evaluation pass location or a big enough profiled data
+        /// Finds the first ancestor of parentId (which could be itself) that is either an evaluation pass location or a big enough profiled data.
         /// </summary>
         private static long? FindBigEnoughParentId(IDictionary<long, Pair<EvaluationLocation, ProfiledLocation>> idTable,
             long? parentId)
@@ -271,11 +274,11 @@ private static ProfiledLocation AggregateProfiledLocation(ProfiledLocation locat
         }
 
         /// <summary>
-        /// Pretty prints the aggregated results and saves it to disk
+        /// Pretty prints the aggregated results and saves it to disk.
         /// </summary>
         /// <remarks>
         /// If the extension of the file to log is 'md', markdown content is generated. Otherwise, it falls 
-        /// back to a tab separated format
+        /// back to a tab separated format.
         /// </remarks>
         private void GenerateProfilerReport()
         {

src/Framework/Sdk/SdkReference.cs

@@ -44,10 +44,11 @@ public SdkReference(string name, string version, string minimumVersion)
         /// </summary>
         public string MinimumVersion { get; }
 
-        /// <summary>
-        /// </summary>
-        /// <param name="other"></param>
-        /// <returns></returns>
+        /// <summary>Indicates whether the current object is equal to another object of the same type.</summary>
+        /// <param name="other">An object to compare with this object.</param>
+        /// <returns>
+        ///   <see langword="true" /> if the current object is equal to the <paramref name="other" /> parameter; otherwise, <see langword="false" />.
+        /// </returns>
         public bool Equals(SdkReference other)
         {
             if (other is null) return false;

src/Framework/Sdk/SdkResolver.cs

@@ -30,9 +30,12 @@ public abstract class SdkResolver
         ///     the SDK could not be resolved.  Return <code>null</code> if the resolver is not
         ///     applicable for a particular <see cref="SdkReference"/>.
         ///  </returns>   
-        ///  <remarks>
-        ///    Note: You must use <see cref="Microsoft.Build.Framework.SdkResultFactory"/> to return a result.
-        ///  </remarks>
+        ///  <remarks><format type="text/markdown"><![CDATA[
+        ///  ## Remarks
+        ///  > [!NOTE]
+        ///  > You must use the <xref:Microsoft.Build.Framework.SdkResultFactory> to return a result.
+        ///  ]]></format>
+        /// </remarks>
         /// 
         public abstract SdkResult Resolve(SdkReference sdkReference, SdkResolverContext resolverContext,
             SdkResultFactory factory);

src/Framework/Sdk/SdkResolverContext.cs

@@ -39,8 +39,11 @@ public abstract class SdkResolverContext
         ///     Version of MSBuild currently running.
         /// </summary>
         /// <remarks>
-        ///     File version based on commit height from our public git repository. This is informational
-        ///     and not equal to the assembly version.
+        ///    <format type="text/markdown"><![CDATA[
+        /// ## Remarks
+        ///     
+        /// File version is informational and not equal to the assembly version.
+        /// ]]></format>
         /// </remarks>
         public virtual Version MSBuildVersion { get; protected set; }
 

src/Framework/Sdk/SdkResult.cs

@@ -9,7 +9,11 @@ namespace Microsoft.Build.Framework
     ///     An abstract interface class to indicate SDK resolver success or failure.
     /// </summary>
     /// <remarks>
-    ///   Note: Use <see cref="Microsoft.Build.Framework.SdkResultFactory"/> to create instances of this class. Do not inherit from this class.
+    ///    <format type="text/markdown"><![CDATA[
+    /// ## Remarks
+    /// > [!NOTE]
+    /// > Use <xref:Microsoft.Build.Framework.SdkResultFactory> to create instances of this class. Do not inherit from this class.
+    /// ]]></format>
     /// </remarks>
     public abstract class SdkResult
     {

src/Tasks/CodeTaskFactory.cs

@@ -160,7 +160,7 @@ private static Assembly CurrentDomainOnAssemblyResolve(object sender, ResolveEve
         public Type TaskType { get; private set; }
 
         /// <summary>
-        /// Get the type information for all task parameters
+        /// Get the type information for all task parameters.
         /// </summary>
         public TaskPropertyInfo[] GetTaskParameters()
         {
@@ -170,7 +170,7 @@ public TaskPropertyInfo[] GetTaskParameters()
         }
 
         /// <summary>
-        /// Initialze the task factory
+        /// Initializes the task factory.
         /// </summary>
         public bool Initialize(string taskName, IDictionary<string, TaskPropertyInfo> taskParameters, string taskElementContents, IBuildEngine taskFactoryLoggingHost)
         {
@@ -306,7 +306,7 @@ public bool Initialize(string taskName, IDictionary<string, TaskPropertyInfo> ta
         }
 
         /// <summary>
-        /// Create a taskfactory instance which contains the data that needs to be refreshed between task invocations
+        /// Create a taskfactory instance which contains the data that needs to be refreshed between task invocations.
         /// </summary>
         public ITask CreateTask(IBuildEngine loggingHost)
         {

src/Tasks/Copy.cs

@@ -101,26 +101,26 @@ public Copy()
         public ITaskItem DestinationFolder { get; set; }
 
         /// <summary>
-        /// How many times to attempt to copy, if all previous
-        /// attempts failed. Defaults to zero.
-        /// Warning: using retries may mask a synchronization problem in your
-        /// build process.
+        /// Gets or sets the number of times to attempt to copy, if all previous attempts failed.
+        /// Warning: using retries may mask a synchronization problem in your build process.
         /// </summary>
         public int Retries { get; set; } = 10;
 
         /// <summary>
-        /// Delay between any necessary retries.
+        /// Gets or sets the delay, in milliseconds, between any necessary retries.
         /// Defaults to <see cref="RetryDelayMillisecondsDefault">RetryDelayMillisecondsDefault</see>
         /// </summary>
         public int RetryDelayMilliseconds { get; set; }
 
         /// <summary>
-        /// Create Hard Links for the copied files rather than copy the files if possible to do so
+        /// Gets or sets a value that indicates whether to use hard links for the copied files
+        /// rather than copy the files, if it's possible to do so.
         /// </summary>
         public bool UseHardlinksIfPossible { get; set; }
 
         /// <summary>
-        /// Create Symbolic Links for the copied files rather than copy the files if possible to do so
+        /// Gets or sets a value that indicates whether to create symbolic links for the copied files
+        /// rather than copy the files, if it's possible to do so.
         /// </summary>
         public bool UseSymboliclinksIfPossible { get; set; } = s_forceSymlinks;
 
@@ -144,7 +144,7 @@ public Copy()
         public bool WroteAtLeastOneFile { get; private set; }
 
         /// <summary>
-        /// Whether to overwrite files in the destination
+        /// Gets or sets a value that indicates whether to overwrite files in the destination
         /// that have the read-only attribute set.
         /// </summary>
         public bool OverwriteReadOnlyFiles { get; set; }

src/Tasks/Hash.cs

@@ -13,8 +13,11 @@ namespace Microsoft.Build.Tasks
     /// Generates a hash of a given ItemGroup items. Metadata is not considered in the hash.
     /// </summary>
     /// <remarks>
-    /// Currently uses SHA1. Implementation subject to change between MSBuild versions. Not
-    /// intended as a cryptographic security measure, only uniqueness between build executions.
+    ///    <format type="text/markdown"><![CDATA[
+    /// ## Remarks
+    /// Currently uses SHA1. The implementation is subject to change between MSBuild versions.
+    /// This class is not intended as a cryptographic security measure, only for uniqueness between build executions.
+    /// ]]></format>
     /// </remarks>
     public class Hash : TaskExtension
     {

src/Tasks/Unzip.cs

@@ -46,12 +46,12 @@ public sealed class Unzip : TaskExtension, ICancelableTask
         public ITaskItem DestinationFolder { get; set; }
 
         /// <summary>
-        /// Gets or sets a value indicating whether read-only files should be overwritten.
+        /// Gets or sets a value that indicates whether read-only files should be overwritten.
         /// </summary>
         public bool OverwriteReadOnlyFiles { get; set; }
 
         /// <summary>
-        /// Gets or sets a value indicating whether files should be skipped if the destination is unchanged.
+        /// Gets or sets a value that indicates whether files should be skipped if the destination is unchanged.
         /// </summary>
         public bool SkipUnchangedFiles { get; set; } = true;
 
@@ -62,12 +62,12 @@ public sealed class Unzip : TaskExtension, ICancelableTask
         public ITaskItem[] SourceFiles { get; set; }
 
         /// <summary>
-        /// Gets or sets an MSBuild glob expression that will be used to determine which files to include being unzipped from the archive.
+        /// Gets or sets an MSBuild glob expression that specifies which files to include being unzipped from the archive.
         /// </summary>
         public string Include { get; set; }
 
         /// <summary>
-        /// Gets or sets an MSBuild glob expression that will be used to determine which files to exclude from being unzipped from the archive.
+        /// Gets or sets an MSBuild glob expression that specifies which files to exclude from being unzipped from the archive.
         /// </summary>
         public string Exclude { get; set; }