SA1004 Documentation line should begin with a space (#7204)

elachlan · web-flow · commit 6ab50263b948 · 2022-01-10T08:07:54.000-08:00
* SA1004 Documentation line should begin with a space

* Fixes from code review

* revert changes to deprecated

* revert changes Sdk/SdkResolver.cs

* enable warning on SA1004
diff --git a/eng/Common.globalconfig b/eng/Common.globalconfig
@@ -711,7 +711,7 @@ dotnet_diagnostic.SA1002.severity = suggestion
 dotnet_diagnostic.SA1003.severity = none
 
 # Documentation line should begin with a space
-dotnet_diagnostic.SA1004.severity = suggestion
+dotnet_diagnostic.SA1004.severity = warning
 
 # Single line comment should begin with a space
 dotnet_diagnostic.SA1005.severity = suggestion
diff --git a/src/Build.OM.UnitTests/ObjectModelRemoting/RemoteProjectsProviderMock/EvaluationLinkMocks/MockProjectItemDefinitionLink.cs b/src/Build.OM.UnitTests/ObjectModelRemoting/RemoteProjectsProviderMock/EvaluationLinkMocks/MockProjectItemDefinitionLink.cs
@@ -18,7 +18,7 @@ public override ProjectItemDefinition CreateLinkedObject(IImportHolder holder)
         }
 
 
-        ///  ProjectItemDefinitionLink remoting
+        /// ProjectItemDefinitionLink remoting
         public MockProjectLinkRemoter Project => this.OwningCollection.Export<Project, MockProjectLinkRemoter>(this.Source.Project);
         public string ItemType => this.Source.ItemType;
         public ICollection<MockProjectMetadataLinkRemoter> Metadata => this.OwningCollection.ExportCollection<ProjectMetadata, MockProjectMetadataLinkRemoter>(this.Source.Metadata);
diff --git a/src/Build.OM.UnitTests/ObjectModelRemoting/RemoteProjectsProviderMock/EvaluationLinkMocks/MockProjectItemLink.cs b/src/Build.OM.UnitTests/ObjectModelRemoting/RemoteProjectsProviderMock/EvaluationLinkMocks/MockProjectItemLink.cs
@@ -19,7 +19,7 @@ public override ProjectItem CreateLinkedObject(IImportHolder holder)
         }
 
 
-        ///  ProjectItemLink remoting
+        /// ProjectItemLink remoting
         public MockProjectLinkRemoter Project => this.OwningCollection.Export<Project, MockProjectLinkRemoter>(this.Source.Project);
         public MockProjectItemElementLinkRemoter Xml => (MockProjectItemElementLinkRemoter)this.OwningCollection.ExportElement(this.Source.Xml);
         public string EvaluatedInclude => this.Source.EvaluatedInclude;
diff --git a/src/Build.OM.UnitTests/ObjectModelRemoting/RemoteProjectsProviderMock/EvaluationLinkMocks/MockProjectLink.cs b/src/Build.OM.UnitTests/ObjectModelRemoting/RemoteProjectsProviderMock/EvaluationLinkMocks/MockProjectLink.cs
@@ -25,7 +25,7 @@ public override Project CreateLinkedObject(IImportHolder holder)
         }
 
 
-        ///  ProjectLink remoting
+        /// ProjectLink remoting
         public MockProjectElementLinkRemoter Xml => this.OwningCollection.ExportElement(this.Source.Xml);
 
         public bool ThrowInsteadOfSplittingItemElement { get => this.Source.ThrowInsteadOfSplittingItemElement; set => this.Source.ThrowInsteadOfSplittingItemElement = value; }
diff --git a/src/Build.OM.UnitTests/ObjectModelRemoting/RemoteProjectsProviderMock/EvaluationLinkMocks/MockProjectMetadataLink.cs b/src/Build.OM.UnitTests/ObjectModelRemoting/RemoteProjectsProviderMock/EvaluationLinkMocks/MockProjectMetadataLink.cs
@@ -18,7 +18,7 @@ public override ProjectMetadata CreateLinkedObject(IImportHolder holder)
         }
 
 
-        ///  ProjectMetadataLink remoting
+        /// ProjectMetadataLink remoting
         public object Parent
         {
             get
diff --git a/src/Build.OM.UnitTests/ObjectModelRemoting/RemoteProjectsProviderMock/EvaluationLinkMocks/MockProjectPropertyLink.cs b/src/Build.OM.UnitTests/ObjectModelRemoting/RemoteProjectsProviderMock/EvaluationLinkMocks/MockProjectPropertyLink.cs
@@ -18,7 +18,7 @@ public override ProjectProperty CreateLinkedObject(IImportHolder holder)
         }
 
 
-        ///  ProjectPropertyLink remoting
+        /// ProjectPropertyLink remoting
         public MockProjectLinkRemoter Project => this.OwningCollection.Export<Project, MockProjectLinkRemoter>(this.Source.Project);
         public MockProjectPropertyElementLinkRemoter Xml => (MockProjectPropertyElementLinkRemoter)this.ExportElement(this.Source.Xml);
         public string Name => this.Source.Name;
diff --git a/src/Build.UnitTests/BackEnd/LoggingServiceFactory_Tests.cs b/src/Build.UnitTests/BackEnd/LoggingServiceFactory_Tests.cs
@@ -10,7 +10,7 @@
 namespace Microsoft.Build.UnitTests.Logging
 {
     /// <summary>
-    ///Test the Factory to create components of the type LoggingService
+    /// Test the Factory to create components of the type LoggingService
     /// </summary>
     public class LoggingServiceFactory_Tests
     {
diff --git a/src/Build/BackEnd/Components/Logging/ILoggingService.cs b/src/Build/BackEnd/Components/Logging/ILoggingService.cs
@@ -269,7 +269,7 @@ MessageImportance MinimumRequiredMessageImportance
         /// Register an logger which expects all logging events from the system
         /// </summary>
         /// <param name="logger">The logger to register.</param>
-        ///<returns value="bool">True if the central was registered. False if the central logger was already registered</returns>
+        /// <returns value="bool">True if the central was registered. False if the central logger was already registered</returns>
         bool RegisterLogger(ILogger logger);
 
         /// <summary>
diff --git a/src/Build/BackEnd/Shared/BuildRequestConfiguration.cs b/src/Build/BackEnd/Shared/BuildRequestConfiguration.cs
@@ -123,7 +123,7 @@ internal class BuildRequestConfiguration : IEquatable<BuildRequestConfiguration>
         /// </summary>
         private int _resultsNodeId = Scheduler.InvalidNodeId;
 
-        ///<summary>
+        /// <summary>
         /// Holds a snapshot of the environment at the time we blocked.
         /// </summary>
         private Dictionary<string, string> _savedEnvironmentVariables;
diff --git a/src/Build/Construction/Solution/SolutionProjectGenerator.cs b/src/Build/Construction/Solution/SolutionProjectGenerator.cs
@@ -1976,9 +1976,9 @@ private void AddValidateProjectsTarget(ProjectInstance traversalProject, List<Pr
             }
         }
 
-        ///<summary>
+        /// <summary>
         /// Creates the target used to build all of the references in the traversal project.
-        ///</summary>
+        /// </summary>
         private static void AddTraversalReferencesTarget(ProjectInstance traversalProject, string targetName, string outputItem)
         {
             string outputItemAsItem = null;
diff --git a/src/Build/Definition/Project.cs b/src/Build/Definition/Project.cs
@@ -857,38 +857,48 @@ public static string GetEvaluatedItemIncludeEscaped(ProjectItemDefinition item)
         /// <example>
         ///
         /// <code>
-        ///<P>*.txt</P>
+        /// <![CDATA[
+        /// <P>*.txt</P>
         ///
-        ///<Bar Include="bar"/> (both outside and inside project cone)
-        ///<Zar Include="C:\**\*.foo"/> (both outside and inside project cone)
-        ///<Foo Include="*.a;*.b" Exclude="3.a"/>
-        ///<Foo Remove="2.a" />
-        ///<Foo Include="**\*.b" Exclude="1.b;**\obj\*.b;**\bar\*.b"/>
-        ///<Foo Include="$(P)"/>
-        ///<Foo Include="*.a;@(Bar);3.a"/> (If Bar has globs, they will have been included when querying Bar ProjectItems for globs)
-        ///<Foo Include="*.cs" Exclude="@(Bar)"/>
-        ///</code>
+        /// <Bar Include="bar"/> (both outside and inside project cone)
+        /// <Zar Include="C:\**\*.foo"/> (both outside and inside project cone)
+        /// <Foo Include="*.a;*.b" Exclude="3.a"/>
+        /// <Foo Remove="2.a" />
+        /// <Foo Include="**\*.b" Exclude="1.b;**\obj\*.b;**\bar\*.b"/>
+        /// <Foo Include="$(P)"/>
+        /// <Foo Include="*.a;@(Bar);3.a"/> (If Bar has globs, they will have been included when querying Bar ProjectItems for globs)
+        /// <Foo Include="*.cs" Exclude="@(Bar)"/>
+        /// ]]>
+        /// </code>
         ///
-        ///Example result:
-        ///[
-        ///GlobResult(glob: "C:\**\*.foo", exclude: []),
-        ///GlobResult(glob: ["*.a", "*.b"], exclude=["3.a"], remove=["2.a"]),
-        ///GlobResult(glob: "**\*.b", exclude=["1.b, **\obj\*.b", **\bar\*.b"]),
-        ///GlobResult(glob: "*.txt", exclude=[]),
-        ///GlobResult(glob: "*.a", exclude=[]),
-        ///GlobResult(glob: "*.cs", exclude=["bar"])
-        ///].
+        /// Example result:
+        /// <code>
+        /// <![CDATA[
+        /// [
+        /// GlobResult(glob: "C:\**\*.foo", exclude: []),
+        /// GlobResult(glob: ["*.a", "*.b"], exclude=["3.a"], remove=["2.a"]),
+        /// GlobResult(glob: "**\*.b", exclude=["1.b, **\obj\*.b", **\bar\*.b"]),
+        /// GlobResult(glob: "*.txt", exclude=[]),
+        /// GlobResult(glob: "*.a", exclude=[]),
+        /// GlobResult(glob: "*.cs", exclude=["bar"])
+        /// ].
+        /// ]]>
+        /// </code>
         /// </example>
         /// <remarks>
+        /// <para>
         /// <see cref="GlobResult.MsBuildGlob"/> is a <see cref="IMSBuildGlob"/> that combines all globs in the include element and ignores
         /// all the fragments in the exclude attribute and all the fragments in all Remove elements that apply to the include element.
+        /// </para>
         ///
         /// Users can construct a composite glob that incorporates all the globs in the Project:
         /// <code>
+        /// <![CDATA[
         /// var uberGlob = new CompositeGlob(project.GetAllGlobs().Select(r => r.MSBuildGlob).ToArray());
         /// uberGlob.IsMatch("foo.cs");
+        /// ]]>
         /// </code>
-        ///
+        /// 
         /// </remarks>
         /// <returns>
         /// List of <see cref="GlobResult"/>.
diff --git a/src/Build/Evaluation/IntrinsicFunctions.cs b/src/Build/Evaluation/IntrinsicFunctions.cs
@@ -350,7 +350,7 @@ internal static string ValueOrDefault(string conditionValue, string defaultValue
             }
         }
 
-        ///<summary>
+        /// <summary>
         /// Hash the string independent of bitness and target framework.
         /// </summary>
         internal static int StableStringHash(string toHash)
diff --git a/src/Framework/BuildEventContext.cs b/src/Framework/BuildEventContext.cs
@@ -27,7 +27,7 @@ public class BuildEventContext
         private readonly int _targetId;
 
         /// <summary>
-        ///The node-unique project request context the event was in
+        /// The node-unique project request context the event was in
         /// </summary>
         private readonly int _projectContextId;
 
diff --git a/src/Framework/Sdk/SdkResolver.cs b/src/Framework/Sdk/SdkResolver.cs
@@ -6,40 +6,41 @@
 namespace Microsoft.Build.Framework
 {
     /// <summary>
-    ///     An abstract interface for classes that can resolve a Software Development Kit (SDK).
+    /// An abstract interface for classes that can resolve a Software Development Kit (SDK).
     /// </summary>
     public abstract class SdkResolver
     {
         /// <summary>
-        ///     Name of the SDK resolver to be displayed in build output log.
+        /// Gets the name of the <see cref="SdkResolver"/> to be displayed in build output log.
         /// </summary>
         public abstract string Name { get; }
 
         /// <summary>
-        ///     Gets the self-described resolution priority order. MSBuild will sort resolvers
-        ///     by this value.
+        /// Gets the self-described resolution priority order. MSBuild will sort resolvers
+        /// by this value.
         /// </summary>
         public abstract int Priority { get; }
 
         /// <summary>
-        ///     Resolves the specified SDK reference.
+        /// Resolves the specified SDK reference.
         /// </summary>
         /// <param name="sdkReference">A <see cref="SdkReference" /> containing the referenced SDKs be resolved.</param>
         /// <param name="resolverContext">Context for resolving the SDK.</param>
         /// <param name="factory">Factory class to create an <see cref="SdkResult" /></param>
         /// <returns>
-        ///     An <see cref="SdkResult" /> containing the resolved SDKs or associated error / reason
-        ///     the SDK could not be resolved.  Return <code>null</code> if the resolver is not
-        ///     applicable for a particular <see cref="SdkReference"/>.
-        ///  </returns>   
-        ///  <remarks><format type="text/markdown"><![CDATA[
+        /// An <see cref="SdkResult" /> containing the resolved SDKs or associated error / reason
+        /// the SDK could not be resolved.  Return <code>null</code> if the resolver is not
+        /// applicable for a particular <see cref="SdkReference"/>.
+        /// </returns>   
+        /// <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);
+        public abstract SdkResult Resolve(SdkReference sdkReference,
+                                          SdkResolverContext resolverContext,
+                                          SdkResultFactory factory);
     }
 }
diff --git a/src/Tasks.UnitTests/AssemblyDependency/Miscellaneous.cs b/src/Tasks.UnitTests/AssemblyDependency/Miscellaneous.cs
@@ -7103,7 +7103,7 @@ public void TestProfileAndSubset2()
         /// Verify setting certain combinations of Profile parameters will case an error to be logged and rar to fail execution.
         ///
         /// Test the case where the profile name is not set and ProfileFullFrameworkFolders is set.
-        ///</summary>
+        /// </summary>
         [Fact]
         public void TestProfileParameterCombinations()
         {
@@ -7118,7 +7118,7 @@ public void TestProfileParameterCombinations()
         /// <summary>
         /// Verify when the frameworkdirectory metadata is not set on the ProfileFullFrameworkAssemblyTables that an
         /// error is logged and rar fails.
-        ///</summary>
+        /// </summary>
         [Fact]
         public void TestFrameworkDirectoryMetadata()
         {
@@ -7179,7 +7179,7 @@ private void InitializeMockEngine(out ReferenceTable referenceTable, out MockEng
         }
 
         /// <summary>
-        ///Initialize the black list and use it to remove references from the reference table
+        /// Initialize the black list and use it to remove references from the reference table
         /// </summary>
         private void InitializeExclusionList(ReferenceTable referenceTable, AssemblyNameExtension[] assembliesForBlackList, out Dictionary<string, string> blackList)
         {
@@ -7741,19 +7741,24 @@ public void Regress397129_HandleInvalidDirectoriesAndFiles_Case2()
             Execute(t);
         }
 
+        /// <summary>
         /// Consider this dependency chain:
         ///
         /// App
-        ///   References - A
-        ///        Depends on B
-        ///        Will be found by hintpath.
-        ///   References -B
-        ///        No hintpath
-        ///        Exists in A.dll's folder.
-        ///
+        /// <code>
+        /// <![CDATA[
+        /// References - A
+        ///      Depends on B
+        ///      Will be found by hintpath.
+        /// References -B
+        ///      No hintpath
+        ///      Exists in A.dll's folder.
+        /// ]]>
+        /// </code>
         /// B.dll should be unresolved even though its in A's folder because primary resolution needs to work
         /// without looking at dependencies because of the load-time perf scenarios don't look at dependencies.
         /// We must be consistent between primaries resolved with FindDependencies=true and FindDependencies=false.
+        /// </summary>
         [Fact]
         public void ByDesignRelatedTo454863_PrimaryReferencesDontResolveToParentFolders()
         {
diff --git a/src/Tasks.UnitTests/AssemblyDependency/SpecificVersionPrimary.cs b/src/Tasks.UnitTests/AssemblyDependency/SpecificVersionPrimary.cs
@@ -80,19 +80,29 @@ public void Exists()
 
         /// <summary>
         /// In this case,
-        /// - A single primary version-strict reference was passed in to assembly version 1.0.0.0
-        /// - An app.config was passed in that promotes a *different* assembly version name from 
-        //    1.0.0.0 to 2.0.0.0
-        /// - Version 1.0.0.0 of the file exists.
-        /// - Version 2.0.0.0 of the file exists.
+        /// <list type="bullet">
+        /// <item>A single primary version-strict reference was passed in to assembly version 1.0.0.0</item>
+        /// <item>
+        /// An app.config was passed in that promotes a *different* assembly version name from 
+        /// 1.0.0.0 to 2.0.0.0
+        /// </item>
+        /// <item>Version 1.0.0.0 of the file exists.</item>
+        /// <item>Version 2.0.0.0 of the file exists.</item>
+        /// </list>
         /// Expected:
-        /// -- The resulting assembly returned should be 1.0.0.0.
+        /// <list type="bullet">
+        /// <item>The resulting assembly returned should be 1.0.0.0.</item>
+        /// </list>
         /// Rationale:
         /// Primary references are never unified. This is because:
-        /// (a) The user expects that a primary reference will be respected.
-        /// (b) When FindDependencies is false and AutoUnify is true, we'd have to find all 
-        ///     dependencies anyway to make things work consistently. This would be a significant
-        ///     perf hit when loading large solutions.
+        /// <list type="number">
+        /// <item>
+        /// The user expects that a primary reference will be respected.</item>
+        /// <item>When FindDependencies is false and AutoUnify is true, we'd have to find all 
+        /// dependencies anyway to make things work consistently. This would be a significant
+        /// perf hit when loading large solutions.
+        /// </item>
+        /// </list>
         /// </summary>
         [Fact]
         [Trait("Category", "mono-osx-failing")]
diff --git a/src/Tasks/FindInvalidProjectReferences.cs b/src/Tasks/FindInvalidProjectReferences.cs
@@ -17,7 +17,7 @@ public class FindInvalidProjectReferences : TaskExtension
     {
         #region Fields
 
-        ///<summary>
+        /// <summary>
         /// Regex for breaking up the platform moniker
         /// Example: XNA, Version=8.0
         /// </summary>
diff --git a/src/Tasks/InstalledSDKResolver.cs b/src/Tasks/InstalledSDKResolver.cs
@@ -12,7 +12,7 @@
 namespace Microsoft.Build.Tasks
 {
     /// <summary>
-    ///There is no search path element because the only way to get this resolver is by having the SDKName metadata on the reference.
+    /// There is no search path element because the only way to get this resolver is by having the SDKName metadata on the reference.
     /// </summary>
     internal class InstalledSDKResolver : Resolver
     {
diff --git a/src/Tasks/ResolveSDKReference.cs b/src/Tasks/ResolveSDKReference.cs
@@ -23,7 +23,7 @@ public class ResolveSDKReference : TaskExtension
     {
         #region fields
 
-        ///<summary>
+        /// <summary>
         /// Regex for breaking up the sdk reference include into pieces.
         /// Example: XNA, Version=8.0
         /// </summary>
diff --git a/src/Tasks/RoslynCodeTaskFactory/RoslynCodeTaskFactory.cs b/src/Tasks/RoslynCodeTaskFactory/RoslynCodeTaskFactory.cs

Original file line number	Diff line number	Diff line change
`@@ -18,7 +18,7 @@ public override ProjectItemDefinition CreateLinkedObject(IImportHolder holder)`
`18`	`18`	`}`
`19`	`19`
`20`	`20`
`21`		`- /// ProjectItemDefinitionLink remoting`
	`21`	`+ /// ProjectItemDefinitionLink remoting`
`22`	`22`	`public MockProjectLinkRemoter Project => this.OwningCollection.Export<Project, MockProjectLinkRemoter>(this.Source.Project);`
`23`	`23`	`public string ItemType => this.Source.ItemType;`
`24`	`24`	`public ICollection<MockProjectMetadataLinkRemoter> Metadata => this.OwningCollection.ExportCollection<ProjectMetadata, MockProjectMetadataLinkRemoter>(this.Source.Metadata);`
Original file line number	Diff line number	Diff line change
`@@ -19,7 +19,7 @@ public override ProjectItem CreateLinkedObject(IImportHolder holder)`
`19`	`19`	`}`
`20`	`20`
`21`	`21`
`22`		`- /// ProjectItemLink remoting`
	`22`	`+ /// ProjectItemLink remoting`
`23`	`23`	`public MockProjectLinkRemoter Project => this.OwningCollection.Export<Project, MockProjectLinkRemoter>(this.Source.Project);`
`24`	`24`	`public MockProjectItemElementLinkRemoter Xml => (MockProjectItemElementLinkRemoter)this.OwningCollection.ExportElement(this.Source.Xml);`
`25`	`25`	`public string EvaluatedInclude => this.Source.EvaluatedInclude;`
Original file line number	Diff line number	Diff line change
`@@ -25,7 +25,7 @@ public override Project CreateLinkedObject(IImportHolder holder)`
`25`	`25`	`}`
`26`	`26`
`27`	`27`
`28`		`- /// ProjectLink remoting`
	`28`	`+ /// ProjectLink remoting`
`29`	`29`	`public MockProjectElementLinkRemoter Xml => this.OwningCollection.ExportElement(this.Source.Xml);`
`30`	`30`
`31`	`31`	`public bool ThrowInsteadOfSplittingItemElement { get => this.Source.ThrowInsteadOfSplittingItemElement; set => this.Source.ThrowInsteadOfSplittingItemElement = value; }`
Original file line number	Diff line number	Diff line change
`@@ -10,7 +10,7 @@`
`10`	`10`	`namespace Microsoft.Build.UnitTests.Logging`
`11`	`11`	`{`
`12`	`12`	`/// <summary>`
`13`		`- ///Test the Factory to create components of the type LoggingService`
	`13`	`+ /// Test the Factory to create components of the type LoggingService`
`14`	`14`	`/// </summary>`
`15`	`15`	`public class LoggingServiceFactory_Tests`
`16`	`16`	`{`
Original file line number	Diff line number	Diff line change
`@@ -1976,9 +1976,9 @@ private void AddValidateProjectsTarget(ProjectInstance traversalProject, List<Pr`
`1976`	`1976`	`}`
`1977`	`1977`	`}`
`1978`	`1978`
`1979`		`- ///<summary>`
	`1979`	`+ /// <summary>`
`1980`	`1980`	`/// Creates the target used to build all of the references in the traversal project.`
`1981`		`- ///</summary>`
	`1981`	`+ /// </summary>`
`1982`	`1982`	`private static void AddTraversalReferencesTarget(ProjectInstance traversalProject, string targetName, string outputItem)`
`1983`	`1983`	`{`
`1984`	`1984`	`string outputItemAsItem = null;`