From 04ca2be5fd85baf2de26cd50f15bb1a0309b8034 Mon Sep 17 00:00:00 2001
From: Nirmal Guru <Nirmal4G@gmail.com>
Date: Sat, 31 Jul 2021 08:31:12 +0530
Subject: [PATCH] Add, Update and Format build Comments

- Remove redundant comments.
- Add missing comments on certain code blocks.
- Format code in comments with proper quote style.
---
 Directory.Build.targets                            |  5 +++++
 build/Community.Toolkit.Common.props               |  6 +++---
 build/Community.Toolkit.Common.targets             |  1 -
 build/Community.Toolkit.TextTemplates.targets      |  4 +++-
 .../CommunityToolkit.Diagnostics.csproj            |  4 ++++
 ...tyToolkit.Mvvm.SourceGenerators.Roslyn40.csproj |  5 +++++
 ...tyToolkit.Mvvm.SourceGenerators.Roslyn43.csproj |  5 +++++
 .../CommunityToolkit.Mvvm.csproj                   | 14 ++++++++++----
 .../CommunityToolkit.Mvvm.targets                  | 10 +++++-----
 src/Directory.Build.props                          |  1 +
 src/Directory.Build.targets                        |  4 ++++
 tests/Directory.Build.props                        |  6 ++++++
 12 files changed, 51 insertions(+), 14 deletions(-)

diff --git a/Directory.Build.targets b/Directory.Build.targets
index c51d83ac5..6b6e9b4e1 100644
--- a/Directory.Build.targets
+++ b/Directory.Build.targets
@@ -2,6 +2,11 @@
 
   <Import Project="$(BuildToolsDirectory)Community.Toolkit.Common.targets" />
 
+  <!--
+      The Git Version task from `Nerdbank.GitVersioning` overwrites the `InformationalVersion`
+      that was supposed to hold the `SourceRevisionId`. Hence, Add the `SourceRevisionId`
+      into Assembly Metadata with the `CommitHash` key.
+  -->
   <Target Name="AddCommitHashToAssemblyAttributes" BeforeTargets="GetAssemblyAttributes">
     <ItemGroup>
       <AssemblyAttribute Include="System.Reflection.AssemblyMetadataAttribute" Condition="'$(SourceRevisionId)' != ''">
diff --git a/build/Community.Toolkit.Common.props b/build/Community.Toolkit.Common.props
index 71e8b5e9d..fd4e8daec 100644
--- a/build/Community.Toolkit.Common.props
+++ b/build/Community.Toolkit.Common.props
@@ -13,9 +13,9 @@
   </PropertyGroup>
 
   <!--
-      Suppress ref safety warnings in unsafe contexts (see https://github.com/dotnet/csharplang/issues/6476).
-      This is used eg. to replace Unsafe.SizeOf<T>() calls with just sizeof(T). The warning is not necessary
-      since in order to use these APIs the caller already has to be in an unsafe context.
+      Suppress `ref` usage safety warnings in unsafe contexts (see https://github.com/dotnet/csharplang/issues/6476).
+      This is used to replace `Unsafe.*` calls with standard language notations (e.g., `Unsafe.SizeOf<T>()` to `sizeof(T)`).
+      The `CS8500` warning is not necessary, since in order to use these APIs the caller already has to be in an unsafe context.
   -->
   <PropertyGroup>
     <NoWarn>$(NoWarn);CS8500</NoWarn>
diff --git a/build/Community.Toolkit.Common.targets b/build/Community.Toolkit.Common.targets
index fe9c21020..bce42789f 100644
--- a/build/Community.Toolkit.Common.targets
+++ b/build/Community.Toolkit.Common.targets
@@ -14,7 +14,6 @@
   </PropertyGroup>
 
   <PropertyGroup Condition="'$(IsPackable)' == 'true'">
-    <!-- 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/build/Community.Toolkit.TextTemplates.targets b/build/Community.Toolkit.TextTemplates.targets
index 0df023483..abf76ca3d 100644
--- a/build/Community.Toolkit.TextTemplates.targets
+++ b/build/Community.Toolkit.TextTemplates.targets
@@ -1,10 +1,11 @@
 <Project>
 
-  <!-- T4 service used by the Guard APIs -->
+  <!-- T4 text template service used by the Visual Studio project system -->
   <ItemGroup>
     <Service Include="{508349b6-6b84-4df5-91f0-309beebad82d}" />
   </ItemGroup>
 
+  <!-- Using T4 text templates to generate sources -->
   <ItemGroup>
     <None Update="**\*.tt">
       <Generator>TextTemplatingFileGenerator</Generator>
@@ -12,6 +13,7 @@
     </None>
   </ItemGroup>
 
+  <!-- Sources generated based on the above text templates -->
   <ItemGroup>
     <Compile Update="**\*.g.cs">
       <AutoGen>True</AutoGen>
diff --git a/src/CommunityToolkit.Diagnostics/CommunityToolkit.Diagnostics.csproj b/src/CommunityToolkit.Diagnostics/CommunityToolkit.Diagnostics.csproj
index e7bed0556..bb2a3ee5d 100644
--- a/src/CommunityToolkit.Diagnostics/CommunityToolkit.Diagnostics.csproj
+++ b/src/CommunityToolkit.Diagnostics/CommunityToolkit.Diagnostics.csproj
@@ -43,6 +43,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>
\ No newline at end of file
diff --git a/src/CommunityToolkit.Mvvm.SourceGenerators/CommunityToolkit.Mvvm.SourceGenerators.Roslyn40.csproj b/src/CommunityToolkit.Mvvm.SourceGenerators/CommunityToolkit.Mvvm.SourceGenerators.Roslyn40.csproj
index 78fd2bbe8..51b69d2bb 100644
--- a/src/CommunityToolkit.Mvvm.SourceGenerators/CommunityToolkit.Mvvm.SourceGenerators.Roslyn40.csproj
+++ b/src/CommunityToolkit.Mvvm.SourceGenerators/CommunityToolkit.Mvvm.SourceGenerators.Roslyn40.csproj
@@ -5,6 +5,7 @@
     <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">
@@ -14,6 +15,10 @@
     </EmbeddedResource>
   </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/src/CommunityToolkit.Mvvm.SourceGenerators/CommunityToolkit.Mvvm.SourceGenerators.Roslyn43.csproj b/src/CommunityToolkit.Mvvm.SourceGenerators/CommunityToolkit.Mvvm.SourceGenerators.Roslyn43.csproj
index 0c748da9a..158dea734 100644
--- a/src/CommunityToolkit.Mvvm.SourceGenerators/CommunityToolkit.Mvvm.SourceGenerators.Roslyn43.csproj
+++ b/src/CommunityToolkit.Mvvm.SourceGenerators/CommunityToolkit.Mvvm.SourceGenerators.Roslyn43.csproj
@@ -5,6 +5,7 @@
     <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">
@@ -14,6 +15,10 @@
     </EmbeddedResource>
   </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/src/CommunityToolkit.Mvvm/CommunityToolkit.Mvvm.csproj b/src/CommunityToolkit.Mvvm/CommunityToolkit.Mvvm.csproj
index 6a6bb18d3..dc25cee46 100644
--- a/src/CommunityToolkit.Mvvm/CommunityToolkit.Mvvm.csproj
+++ b/src/CommunityToolkit.Mvvm/CommunityToolkit.Mvvm.csproj
@@ -43,8 +43,8 @@
   </ItemGroup>
 
   <!--
-      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" />
@@ -74,8 +74,14 @@
   </ItemGroup>
 
   <!--
-      Pack the source generator to the right package folders (each matching the target Roslyn version).
-      Roslyn will automatically load the highest version compatible with Roslyn's version in the SDK.
+      Pack the source generator build outputs to the correct package folders (for each target Roslyn version)
+      for them to be used as analyzers. Roslyn compilers will automatically load the highest version compatible
+      with the Roslyn's version in the SDK.
+
+      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-roslyn4.0\CommunityToolkit.Mvvm.SourceGenerators.dll" PackagePath="analyzers\dotnet\roslyn4.0\cs" Pack="true" Visible="false" />
diff --git a/src/CommunityToolkit.Mvvm/CommunityToolkit.Mvvm.targets b/src/CommunityToolkit.Mvvm/CommunityToolkit.Mvvm.targets
index 881b9a16c..fe88eb801 100644
--- a/src/CommunityToolkit.Mvvm/CommunityToolkit.Mvvm.targets
+++ b/src/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,9 +14,9 @@
           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'))">
@@ -24,10 +24,10 @@
     </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 -->
       <MVVMToolkitCurrentCompilerVersion>@(MVVMToolkitCurrentCompilerAssemblyIdentity->'%(Version)')</MVVMToolkitCurrentCompilerVersion>
 
-      <!-- The CurrentCompilerVersionIsNotNewEnough property can now be defined based on the Roslyn assembly version -->
+      <!-- The 'MVVMToolkitCurrentCompilerVersionIsNotNewEnough' property can now be defined based on the Roslyn assembly version -->
       <MVVMToolkitCurrentCompilerVersionIsNotNewEnough Condition="$([MSBuild]::VersionLessThan($(MVVMToolkitCurrentCompilerVersion), 4.0))">true</MVVMToolkitCurrentCompilerVersionIsNotNewEnough>
     </PropertyGroup>
 
diff --git a/src/Directory.Build.props b/src/Directory.Build.props
index 96b5b700b..a42e218b6 100644
--- a/src/Directory.Build.props
+++ b/src/Directory.Build.props
@@ -2,6 +2,7 @@
 
   <Import Project="..\$(MSBuildThisFile)" />
 
+  <!-- Common properties for all projects under src folder -->
   <PropertyGroup>
     <IsPackable>true</IsPackable>
     <IsPublishable>true</IsPublishable>
diff --git a/src/Directory.Build.targets b/src/Directory.Build.targets
index 035d9e42c..fa0bd7f59 100644
--- a/src/Directory.Build.targets
+++ b/src/Directory.Build.targets
@@ -2,12 +2,16 @@
 
   <Import Project="..\$(MSBuildThisFile)" />
 
+  <!-- Configure defaults for projects targeting .NET 6 and above -->
   <PropertyGroup Condition="'$(_NET_6_OR_GREATER)' == 'true'">
+    <!-- Enable trimming on supported targets -->
     <IsTrimmable>true</IsTrimmable>
     <EnableTrimAnalyzer>true</EnableTrimAnalyzer>
+    <!-- Define `NETSTANDARD2_1_OR_GREATER` to include .NET Standard 2.1 shared APIs -->
     <DefineConstants>NETSTANDARD2_1_OR_GREATER</DefineConstants>
   </PropertyGroup>
 
+  <!-- Common Assembly and Module attributes across projects -->
   <ItemGroup>
     <Compile Include="$(BuildToolsDirectory)AssemblyInfo.Shared.cs" LinkBase="Properties" Visible="False" />
   </ItemGroup>
diff --git a/tests/Directory.Build.props b/tests/Directory.Build.props
index 9c91d9c2c..673d90b15 100644
--- a/tests/Directory.Build.props
+++ b/tests/Directory.Build.props
@@ -2,6 +2,11 @@
 
   <Import Project="..\$(MSBuildThisFile)" />
 
+  <!--
+      By default, all projects under tests are neither packed nor published.
+      This also includes non-test projects as well. But if it's required then
+      override the following properties only within those projects.
+  -->
   <PropertyGroup>
     <IsPackable>false</IsPackable>
     <IsPublishable>false</IsPublishable>
@@ -10,6 +15,7 @@
 
   <PropertyGroup>
     <IsTestProject>true</IsTestProject>
+    <!-- The MVVM Toolkit unit tests use `Mvvm.ExternalAssembly` project as a `ProjectReference` for testing -->
     <IsTestProject Condition="$(MSBuildProjectName.Contains('Mvvm.ExternalAssembly'))">false</IsTestProject>
   </PropertyGroup>