From a4e79abe1fbce6530db832aebe0cc02b1bdc08ec Mon Sep 17 00:00:00 2001
From: Dominion <Cyberboss@users.noreply.github.com>
Date: Mon, 10 Apr 2023 13:33:41 -0400
Subject: [PATCH] Package documentation and cleanup

---
 .../Tgstation.Server.Api.csproj               |  4 ++
 .../Tgstation.Server.Client.csproj            |  3 +-
 .../Tgstation.Server.Host.Console.csproj      |  3 +-
 .../Tgstation.Server.Host.Service.csproj      |  9 +++--
 .../Tgstation.Server.Host.Watchdog.csproj     |  7 +---
 .../Tgstation.Server.Host.csproj              | 38 +++++++++++++++++--
 6 files changed, 50 insertions(+), 14 deletions(-)

diff --git a/src/Tgstation.Server.Api/Tgstation.Server.Api.csproj b/src/Tgstation.Server.Api/Tgstation.Server.Api.csproj
index f079f488db..c67ed86f87 100644
--- a/src/Tgstation.Server.Api/Tgstation.Server.Api.csproj
+++ b/src/Tgstation.Server.Api/Tgstation.Server.Api.csproj
@@ -46,12 +46,16 @@
   </Target>
 
   <ItemGroup>
+    <!-- Usage: HTTP constants reference -->
     <PackageReference Include="Microsoft.AspNetCore.Http.Extensions" Version="2.2.0" />
+    <!-- Usage: Primary JSON library -->
     <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
+    <!-- Usage: Linting -->
     <PackageReference Include="StyleCop.Analyzers" Version="1.1.118">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
+    <!-- Usage: Data model annotating -->
     <PackageReference Include="System.ComponentModel.Annotations" Version="5.0.0" />
   </ItemGroup>
 
diff --git a/src/Tgstation.Server.Client/Tgstation.Server.Client.csproj b/src/Tgstation.Server.Client/Tgstation.Server.Client.csproj
index 6ef0426a5b..9ea8c721cd 100644
--- a/src/Tgstation.Server.Client/Tgstation.Server.Client.csproj
+++ b/src/Tgstation.Server.Client/Tgstation.Server.Client.csproj
@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
   <Import Project="../../build/Version.props" />
 
   <PropertyGroup>
@@ -32,6 +32,7 @@
   </PropertyGroup>
 
   <ItemGroup>
+    <!-- Usage: Linting -->
     <PackageReference Include="StyleCop.Analyzers" Version="1.1.118">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
diff --git a/src/Tgstation.Server.Host.Console/Tgstation.Server.Host.Console.csproj b/src/Tgstation.Server.Host.Console/Tgstation.Server.Host.Console.csproj
index 9ab96c2f7b..045d8ce9eb 100644
--- a/src/Tgstation.Server.Host.Console/Tgstation.Server.Host.Console.csproj
+++ b/src/Tgstation.Server.Host.Console/Tgstation.Server.Host.Console.csproj
@@ -24,8 +24,9 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <!-- DO NOT UPDATE UNLESS YOU WANT TO DEAL WITH THE LOGGERFACTORY REFACTOR -->
+    <!-- Usage: Console logging plugin -->
     <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="6.0.0" />
+    <!-- Usage: Linting -->
     <PackageReference Include="StyleCop.Analyzers" Version="1.1.118">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
diff --git a/src/Tgstation.Server.Host.Service/Tgstation.Server.Host.Service.csproj b/src/Tgstation.Server.Host.Service/Tgstation.Server.Host.Service.csproj
index 23ad2e5d76..5499f045f7 100644
--- a/src/Tgstation.Server.Host.Service/Tgstation.Server.Host.Service.csproj
+++ b/src/Tgstation.Server.Host.Service/Tgstation.Server.Host.Service.csproj
@@ -23,17 +23,18 @@
   </PropertyGroup>
 
   <ItemGroup>
+    <!-- Usage: Command line argument support -->
     <PackageReference Include="McMaster.Extensions.CommandLineUtils" Version="4.0.2" />
-    <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="6.0.0">
-      <PrivateAssets>all</PrivateAssets>
-      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
-    </PackageReference>
+    <!-- Usage: Windows event log logging plugin -->
     <PackageReference Include="Microsoft.Extensions.Logging.EventLog" Version="6.0.0" />
+    <!-- Usage: Console logging plugin -->
     <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="6.0.0" />
+    <!-- Usage: Linting -->
     <PackageReference Include="StyleCop.Analyzers" Version="1.1.118">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
+    <!-- Usage: OS identification -->
     <PackageReference Include="System.Runtime.InteropServices" Version="4.3.0" />
   </ItemGroup>
 
diff --git a/src/Tgstation.Server.Host.Watchdog/Tgstation.Server.Host.Watchdog.csproj b/src/Tgstation.Server.Host.Watchdog/Tgstation.Server.Host.Watchdog.csproj
index 763e986d9d..972487c7dd 100644
--- a/src/Tgstation.Server.Host.Watchdog/Tgstation.Server.Host.Watchdog.csproj
+++ b/src/Tgstation.Server.Host.Watchdog/Tgstation.Server.Host.Watchdog.csproj
@@ -24,12 +24,9 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="6.0.0">
-      <PrivateAssets>all</PrivateAssets>
-      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
-    </PackageReference>
-    <!-- DO NOT UPDATE UNLESS YOU WANT TO DEAL WITH THE LOGGERFACTORY REFACTOR -->
+    <!-- Usage: Logging abstractions -->
     <PackageReference Include="Microsoft.Extensions.Logging" Version="6.0.0" />
+    <!-- Usage: Linting -->
     <PackageReference Include="StyleCop.Analyzers" Version="1.1.118">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
diff --git a/src/Tgstation.Server.Host/Tgstation.Server.Host.csproj b/src/Tgstation.Server.Host/Tgstation.Server.Host.csproj
index db43392256..ee0278d141 100644
--- a/src/Tgstation.Server.Host/Tgstation.Server.Host.csproj
+++ b/src/Tgstation.Server.Host/Tgstation.Server.Host.csproj
@@ -61,47 +61,79 @@
   </Target>
 
   <ItemGroup>
+    <!-- Usage: Concise throw statements for native Win32 errors -->
     <PackageReference Include="BetterWin32Errors" Version="0.2.0" />
+    <!-- Usage: Interop with BYOND's /world/Topic -->
     <PackageReference Include="Byond.TopicSender" Version="5.0.0" />
+    <!-- Usage: 503'ing request pipeline until server is finished initializing -->
     <PackageReference Include="Cyberboss.AspNetCore.AsyncInitializer" Version="1.2.0" />
+    <!-- Usage: IRC interop -->
     <PackageReference Include="Cyberboss.SmartIrc4net.Standard" Version="0.4.7" />
+    <!-- Usage: Text formatter for Elasticsearch logging plugin -->
     <PackageReference Include="Elastic.CommonSchema.Serilog" Version="1.5.3" />
+    <!-- Usage: GitLab interop -->
     <PackageReference Include="GitLabApiClient" Version="1.8.0" />
-    <!-- Later versions are known to show issues with TGS. Do not upgrade without thorough git testing -->
+    <!-- Usage: git interop -->
+    <!-- Pinned: Later versions are known to show issues with TGS. Do not upgrade without thorough git testing -->
     <PackageReference Include="LibGit2Sharp" Version="0.27.0-preview-0034" />
+    <!-- Usage: JWT injection into HTTP pipeline -->
     <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="6.0.15" />
+    <!-- Usage: Support ""legacy"" Newotonsoft.Json in HTTP pipeline. The rest of our codebase uses Newtonsoft. -->
     <PackageReference Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="6.0.15" />
+    <!-- Usage: Database ORM -->
     <PackageReference Include="Microsoft.EntityFrameworkCore" Version="6.0.15" />
+    <!-- Usage: Automatic migration generation using command line -->
     <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="6.0.15">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
+    <!-- Usage: Sqlite ORM plugin -->
     <PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="6.0.15" />
+    <!-- Usage: MSSQL ORM plugin -->
     <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="6.0.15" />
-    <!-- Required for https://github.com/coverlet-coverage/coverlet/issues/1381 -->
+    <!-- Usage: Included transitively through other packages, workaround for https://github.com/coverlet-coverage/coverlet/issues/1381 -->
     <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="6.0.3" />
+    <!-- Usage: POSIX support for syscalls, signals, and symlinks -->
     <PackageReference Include="Mono.Posix.NETStandard" Version="1.0.0" />
+    <!-- Usage: YAML config plugin -->
     <PackageReference Include="NetEscapades.Configuration.Yaml" Version="3.0.0" />
+    <!-- Usage: PostgresSQL ORM plugin -->
     <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="6.0.8" />
+    <!-- Usage: GitHub.com interop -->
     <PackageReference Include="Octokit" Version="5.0.3" />
+    <!-- Usage: MYSQL/MariaDB ORM plugin -->
     <PackageReference Include="Pomelo.EntityFrameworkCore.MySql" Version="6.0.2" />
-    <!-- 2022.49.0 is the last .NET 6.0 version but has issues -->
+    <!-- Usage: Discord interop -->
+    <!-- Pinned: 2022.49.0 is the last .NET 6.0 version but has issues -->
     <PackageReference Include="Remora.Discord" Version="2022.48.0" />
+    <!-- Usage: Rich logger builder -->
     <PackageReference Include="Serilog.Extensions.Logging" Version="3.1.0" />
+    <!-- Usage: Async logging plugin -->
     <PackageReference Include="Serilog.Sinks.Async" Version="1.5.0" />
+    <!-- Usage: Console logging plugin -->
     <PackageReference Include="Serilog.Sinks.Console" Version="4.1.0" />
+    <!-- Usage: Elasticsearch logging plugin -->
     <PackageReference Include="Serilog.Sinks.Elasticsearch" Version="9.0.0" />
+    <!-- Usage: File logging plugin -->
     <PackageReference Include="Serilog.Sinks.File" Version="5.0.0" />
+    <!-- Usage: Linting -->
     <PackageReference Include="StyleCop.Analyzers" Version="1.1.118">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
+    <!-- Usage: OpenAPI spec generator -->
     <PackageReference Include="Swashbuckle.AspNetCore" Version="6.5.0" />
+    <!-- Usage: Newtonsoft.Json plugin for OpenAPI spec generator -->
     <PackageReference Include="Swashbuckle.AspNetCore.Newtonsoft" Version="6.5.0" />
+    <!-- Usage: Access to raw database connectors primarily for setup wizard -->
     <PackageReference Include="System.Data.SqlClient" Version="4.8.5" />
+    <!-- Usage: Windows authentication plugin allowing searching for users by name -->
     <PackageReference Include="System.DirectoryServices.AccountManagement" Version="6.0.0" />
+    <!-- Usage: JWT plugin needed to undo some Microsoft meddling in the HTTP pipeline -->
     <PackageReference Include="System.IdentityModel.Tokens.Jwt" Version="6.28.1" />
+    <!-- Usage: Identifying owning user of Windows Process objects -->
     <PackageReference Include="System.Management" Version="6.0.0" />
+    <!-- Usage: .DeleteAsync() support for IQueryable<T>s -->
     <PackageReference Include="Z.EntityFramework.Plus.EFCore" Version="6.20.1" />
   </ItemGroup>