Format and Update Comments

- Remove redundant comments. - Add missing comments on certain code blocks. - Format code in comments with proper quote style.
CommunityToolkit · Jun 11, 2022 · 16d9daa · 16d9daa
1 parent f218d1b
commit 16d9daa
Show file tree

Hide file tree

Showing 9 changed files with 41 additions and 17 deletions.
diff --git a/CommunityToolkit.Common/CommunityToolkit.Common.csproj b/CommunityToolkit.Common/CommunityToolkit.Common.csproj
@@ -15,8 +15,9 @@
   </PropertyGroup>
 
   <!--
-      .NET Standard 2.1 and .NET 6 already have [NotNullIfNotNull] and [NotNullWhen].
-       Additionally, also enable trimming support on .NET 6.
+      Use NETSTANDARD2_1_OR_GREATER define to include .NET Standard 2.1 and .NET 6 shared APIs.
+      They already have [NotNullIfNotNull] and [NotNullWhen] attributes built-in.
+      Additionally, enable assembly trimming on .NET 6+.
   -->
   <PropertyGroup Condition="'$(TargetFramework)' == 'net6.0'">
     <DefineConstants>NETSTANDARD2_1_OR_GREATER</DefineConstants>

diff --git a/CommunityToolkit.Diagnostics/CommunityToolkit.Diagnostics.csproj b/CommunityToolkit.Diagnostics/CommunityToolkit.Diagnostics.csproj
@@ -31,7 +31,10 @@
       </ItemGroup>
     </When>
 
-    <!-- Enable trimming support on .NET 6 -->
+    <!--
+        Use NETSTANDARD2_1_OR_GREATER define to include .NET Standard 2.1 and .NET 6 shared APIs.
+        Additionally, enable assembly trimming on .NET 6+.
+    -->
     <When Condition="'$(TargetFramework)' == 'net6.0'">
       <PropertyGroup>
         <DefineConstants>NETSTANDARD2_1_OR_GREATER</DefineConstants>
@@ -41,6 +44,10 @@
     </When>
   </Choose>
 
+  <!--
+      Adds support for generating sources using T4 text templating engine.
+      The Guard APIs in 'Generated' folder is generated using text templates.
+  -->
   <Import Project="$(BuildToolsDirectory)Community.Toolkit.TextTemplates.targets" />
 
 </Project>
diff --git a/CommunityToolkit.HighPerformance/CommunityToolkit.HighPerformance.csproj b/CommunityToolkit.HighPerformance/CommunityToolkit.HighPerformance.csproj
@@ -46,6 +46,8 @@
     </When>
 
     <When Condition="'$(TargetFramework)' == 'netcoreapp3.1'">
+
+      <!-- Use NETSTANDARD2_1_OR_GREATER define to include shared APIs -->
       <PropertyGroup>
         <DefineConstants>NETSTANDARD2_1_OR_GREATER</DefineConstants>
       </PropertyGroup>
@@ -57,8 +59,8 @@
     </When>
 
     <!--
-        NETSTANDARD2_1_OR_GREATER: includes both .NET Standard 2.1, .NET Core 3.1 and .NET 6.
-        Additionally, also enable trimming support on .NET 6.
+        Use NETSTANDARD2_1_OR_GREATER define to include .NET Standard 2.1, .NET Core 3.1 and .NET 6 shared APIs.
+        Additionally, enable assembly trimming on .NET 6+
     -->
     <When Condition="'$(TargetFramework)' == 'net6.0'">
       <PropertyGroup>

diff --git a/CommunityToolkit.Mvvm.SourceGenerators/CommunityToolkit.Mvvm.SourceGenerators.csproj b/CommunityToolkit.Mvvm.SourceGenerators/CommunityToolkit.Mvvm.SourceGenerators.csproj
@@ -5,11 +5,16 @@
     <TargetFramework>netstandard2.0</TargetFramework>
   </PropertyGroup>
 
+  <!-- Sources that are used by Generator logic in the target projects -->
   <ItemGroup>
     <Compile Remove="EmbeddedResources\*.cs" />
     <EmbeddedResource Include="EmbeddedResources\*.cs" CopyToOutputDirectory="PreserveNewest" />
   </ItemGroup>
 
+  <!--
+      These files enables tracking Analyzer releases for the rules that ship from this project.
+      See https://github.com/dotnet/roslyn-analyzers/blob/main/src/Microsoft.CodeAnalysis.Analyzers/ReleaseTrackingAnalyzers.Help.md for more info.
+  -->
   <ItemGroup>
     <AdditionalFiles Include="AnalyzerReleases.Shipped.md" />
     <AdditionalFiles Include="AnalyzerReleases.Unshipped.md" />

diff --git a/CommunityToolkit.Mvvm/CommunityToolkit.Mvvm.csproj b/CommunityToolkit.Mvvm/CommunityToolkit.Mvvm.csproj
@@ -20,15 +20,15 @@
     <PackageTags>MVVM;Toolkit;MVVMToolkit;INotifyPropertyChanged;Observable;IOC;DI;Dependency Injection;Object Messaging;Extensions;Helpers</PackageTags>
   </PropertyGroup>
 
-  <!-- Enable trimming support on .NET 6 -->
+  <!-- Enable assembly trimming on .NET 6+ -->
   <PropertyGroup Condition="'$(TargetFramework)' == 'net6.0'">
     <EnableTrimAnalyzer>true</EnableTrimAnalyzer>
     <IsTrimmable>true</IsTrimmable>
   </PropertyGroup>
 
   <!--
-      Include the custom .targets file to check the source generator.
-      .NET 6 is not needed as it guarantees Roslyn 4.x.
+      Include a custom targets file to check the compiler version required for the source generator.
+      It needs Roslyn 4.x and including the targets in .NET 6+ is not needed as it guarantees the same.
   -->
   <ItemGroup>
     <None Include="CommunityToolkit.Mvvm.targets" Pack="True" PackagePath="build\netstandard2.0" />
@@ -58,7 +58,12 @@
   </ItemGroup>
 
   <!--
-      Pack the source generator to the right package folder
+      Pack the source generator build outputs to the correct package folder for it to be used as an analyzer.
+
+      HACK: The recommended way to pack is to get the build outputs using the project's built-in targets,
+            and include them using NuGet's Pack targets. However, due to a bug in v5 of those targets,
+            the outputs were not included in the package. So, including them directly via final
+            output path and building it first is the only way to ensure they are included.
   -->
   <ItemGroup>
     <None Include="..\CommunityToolkit.Mvvm.SourceGenerators\bin\$(Configuration)\netstandard2.0\CommunityToolkit.Mvvm.SourceGenerators.dll"

diff --git a/CommunityToolkit.Mvvm/CommunityToolkit.Mvvm.targets b/CommunityToolkit.Mvvm/CommunityToolkit.Mvvm.targets
@@ -1,6 +1,6 @@
 <Project>
 
-  <!-- Get the analyzer from the CommunityToolkit.Mvvm NuGet package -->
+  <!-- Get the analyzer from the 'CommunityToolkit.Mvvm' NuGet package -->
   <Target Name="_MVVMToolkitGatherAnalyzers">
     <ItemGroup>
       <_MVVMToolkitAnalyzer Include="@(Analyzer)" Condition="'%(Analyzer.NuGetPackageId)' == 'CommunityToolkit.Mvvm'" />
@@ -14,20 +14,20 @@
           DependsOnTargets="_MVVMToolkitGatherAnalyzers">
 
     <!--
-        Use the CSharpCoreTargetsPath property to find the version of the compiler we are using. This is the same mechanism
+        Use the 'CSharpCoreTargetsPath' property to find the version of the compiler we are using. This is the same mechanism
         MSBuild uses to find the compiler. We could check the assembly version for any compiler assembly (since they all have
-        the same version) but Microsoft.Build.Tasks.CodeAnalysis.dll is where MSBuild loads the compiler tasks from so if
+        the same version) but 'Microsoft.Build.Tasks.CodeAnalysis.dll' is where MSBuild loads the compiler tasks from so if
         someone is getting creative with msbuild tasks/targets this is the "most correct" assembly to check.
     -->
     <GetAssemblyIdentity AssemblyFiles="$([System.IO.Path]::Combine($([System.IO.Path]::GetDirectoryName($(CSharpCoreTargetsPath))), 'Microsoft.Build.Tasks.CodeAnalysis.dll'))">
       <Output TaskParameter="Assemblies" ItemName="CurrentCompilerAssemblyIdentity"/>
     </GetAssemblyIdentity>
 
     <PropertyGroup>
-      <!-- Transform the resulting item from GetAssemblyIdentity into a property representing its assembly version -->
+      <!-- Transform the resulting item from 'GetAssemblyIdentity' task into a property representing its assembly version -->
       <CurrentCompilerVersion>@(CurrentCompilerAssemblyIdentity->'%(Version)')</CurrentCompilerVersion>
 
-      <!-- The CurrentCompilerVersionIsNotNewEnough property can now be defined based on the Roslyn assembly version -->
+      <!-- The 'CurrentCompilerVersionIsNotNewEnough' property can now be defined based on the Roslyn assembly version -->
       <CurrentCompilerVersionIsNotNewEnough Condition="$([MSBuild]::VersionLessThan($(CurrentCompilerVersion), 4.0))">true</CurrentCompilerVersionIsNotNewEnough>
     </PropertyGroup>
 

diff --git a/Directory.Build.targets b/Directory.Build.targets
@@ -2,6 +2,10 @@
 
   <Import Project="$(BuildToolsDirectory)Community.Toolkit.Common.targets" />
 
+  <!--
+      Nerdbank.GitVersioning overwrites the 'InformationalVersion' that was supposed to hold the 'SourceRevisionId'.
+      Hence, Add the 'SourceRevisionId' into the Assembly Metadata with the key 'CommitHash'.
+  -->
   <Target Name="AddCommitHashToAssemblyAttributes" BeforeTargets="GetAssemblyAttributes">
     <ItemGroup>
       <AssemblyAttribute Include="System.Reflection.AssemblyMetadataAttribute" Condition="'$(SourceRevisionId)' != ''">

diff --git a/build/Community.Toolkit.Common.targets b/build/Community.Toolkit.Common.targets
@@ -14,7 +14,6 @@
   </PropertyGroup>
 
   <PropertyGroup Condition="$(IsPackable)">
-    <!-- TODO: Dynamically generate Title if one wasn't set -->
     <Title Condition="'$(Title)' == ''">$(Product) Asset</Title>
     <PackageTags Condition="'$(PackageTags)' != ''">$(CommonTags);$(PackageTags)</PackageTags>
     <PackageTags Condition="'$(PackageTags)' == ''">$(CommonTags)</PackageTags>

diff --git a/tests/CommunityToolkit.Mvvm.ExternalAssembly/CommunityToolkit.Mvvm.ExternalAssembly.csproj b/tests/CommunityToolkit.Mvvm.ExternalAssembly/CommunityToolkit.Mvvm.ExternalAssembly.csproj
@@ -5,8 +5,9 @@
   </PropertyGroup>
 
   <!--
-      Manually apply the properties of test projects to this assembly as well,
-      which is neither a test project not one of the libraries to pack for NuGet.
+      The MVVM Toolkit unit tests use this project to test it as a `ProjectReference`.
+      Since this project is neither packed nor published, those targets can be
+      disabled, and validation warnings can be ignored in those contexts.
   -->
   <PropertyGroup>
     <IsPackable>false</IsPackable>