Add, Update and Format build Comments

- Remove redundant comments. - Add missing comments on certain code blocks. - Format code in comments with proper quote style.
CommunityToolkit · Jan 2, 2023 · 2b0ea88 · 2b0ea88
1 parent 8473017
commit 2b0ea88
Show file tree

Hide file tree

Showing 12 changed files with 51 additions and 14 deletions.
diff --git a/Directory.Build.targets b/Directory.Build.targets
@@ -2,6 +2,11 @@
 
   <Import Project="$(BuildToolsDirectory)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/eng/Toolkit.Common.props b/eng/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/eng/Toolkit.Common.targets b/eng/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/eng/Toolkit.TextTemplates.targets b/eng/Toolkit.TextTemplates.targets
@@ -1,17 +1,19 @@
 <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>
       <LastGenOutput>%(Filename).g.cs</LastGenOutput>
     </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
@@ -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)Toolkit.TextTemplates.targets" />
 
 </Project>
diff --git a/...unityToolkit.Mvvm.SourceGenerators/CommunityToolkit.Mvvm.SourceGenerators.Roslyn40.csproj b/...unityToolkit.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/...unityToolkit.Mvvm.SourceGenerators/CommunityToolkit.Mvvm.SourceGenerators.Roslyn43.csproj b/...unityToolkit.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
@@ -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
@@ -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="MVVMToolkitCurrentCompilerAssemblyIdentity"/>
     </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
@@ -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
@@ -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
@@ -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>