Improve xmldocs

Author: xPaw

ValvePak/ValvePak/ArchiveMD5SectionEntry.cs

@@ -1,12 +1,12 @@
 namespace SteamDatabase.ValvePak
 {
 	/// <summary>
-	/// VPK_ArchiveMD5SectionEntry
+	/// Represents an entry in the VPK archive MD5 section, containing checksum information for a chunk of archive data.
 	/// </summary>
 	public class ArchiveMD5SectionEntry
 	{
 		/// <summary>
-		/// Gets or sets the CRC32 checksum of this entry.
+		/// Gets or sets the archive index.
 		/// </summary>
 		public required uint ArchiveIndex { get; set; }
 
@@ -21,7 +21,7 @@ public class ArchiveMD5SectionEntry
 		public required uint Length { get; set; }
 
 		/// <summary>
-		/// Gets or sets the expected Checksum checksum.
+		/// Gets or sets the expected checksum.
 		/// </summary>
 		public required byte[] Checksum { get; set; }
 	}

ValvePak/ValvePak/CaseInsensitivePackageEntryComparer.cs

@@ -9,7 +9,7 @@ sealed class CaseInsensitivePackageEntryComparer(StringComparison comparison) :
 		public StringComparison Comparison { get; } = comparison;
 
 		/// <remarks>
-		/// Intentionally not comparing TypeName because this comparer is used on Entries which is split by extension already.
+		/// Intentionally not comparing <see cref="PackageEntry.TypeName"/> because this comparer is used on <see cref="Package.Entries"/> which is split by extension already.
 		/// </remarks>
 		public int Compare(PackageEntry? x, PackageEntry? y)
 		{

ValvePak/ValvePak/Package.cs

@@ -10,6 +10,9 @@ namespace SteamDatabase.ValvePak
 	/// </summary>
 	public partial class Package : IDisposable
 	{
+		/// <summary>
+		/// The VPK file signature magic number.
+		/// </summary>
 		public const int MAGIC = 0x55AA1234;
 
 		internal const string Space = " ";
@@ -116,6 +119,9 @@ public void Dispose()
 			GC.SuppressFinalize(this);
 		}
 
+		/// <summary>
+		/// Releases binary reader.
+		/// </summary>
 		protected virtual void Dispose(bool disposing)
 		{
 			if (disposing)
@@ -220,11 +226,11 @@ public void SetFileName(string fileName)
 				return default;
 			}
 
-			/// Searches for a given file entry in the file list after it has been optimized with <see cref="OptimizeEntriesForBinarySearch"/>.
-			/// This also supports case insensitive search by using a different <see cref="StringComparison"/>.
-			///
-			/// Manually implement binary search to avoid allocating new strings for file and directory names.
-			/// See <see cref="MemoryExtensions.BinarySearch{T}(ReadOnlySpan{T}, IComparable{T})"/> for reference.
+			// Searches for a given file entry in the file list after it has been optimized with <see cref="OptimizeEntriesForBinarySearch"/>.
+			// This also supports case insensitive search by using a different <see cref="StringComparison"/>.
+			//
+			// Manually implement binary search to avoid allocating new strings for file and directory names.
+			// See <see cref="MemoryExtensions.BinarySearch{T}(ReadOnlySpan{T}, IComparable{T})"/> for reference.
 
 			int lo = 0;
 
@@ -233,7 +239,7 @@ public void SetFileName(string fileName)
 				var i = (int)(((uint)hi + (uint)lo) >> 1);
 				var entry = entriesForExtension[i];
 
-				/// This code must match <see cref="CaseInsensitivePackageEntryComparer.Compare(PackageEntry, PackageEntry)"/>
+				// This code must match <see cref="CaseInsensitivePackageEntryComparer.Compare(PackageEntry, PackageEntry)"/>
 				var comp = fileName.Length.CompareTo(entry.FileName.Length);
 
 				if (comp == 0)

ValvePak/ValvePak/PackageEntry.cs

@@ -1,5 +1,8 @@
 namespace SteamDatabase.ValvePak
 {
+	/// <summary>
+	/// Represents a file entry in a VPK package.
+	/// </summary>
 	public class PackageEntry
 	{
 		/// <summary>
@@ -12,7 +15,7 @@ public class PackageEntry
 
 		/// <summary>
 		/// Gets or sets the name of the directory this file is in.
-		/// '/' is always used as a dictionary separator in Valve's implementation.
+		/// '/' is always used as a directory separator in Valve's implementation.
 		/// Directory names are also always lower cased in Valve's implementation.
 		/// </summary>
 		public required string DirectoryName { get; set; }
@@ -44,7 +47,7 @@ public class PackageEntry
 		public ushort ArchiveIndex { get; set; }
 
 		/// <summary>
-		/// Gets the length in bytes by adding Length and length of SmallData.
+		/// Gets the length in bytes by adding <see cref="Length"/> and length of <see cref="SmallData"/>.
 		/// </summary>
 		public uint TotalLength
 		{
@@ -96,6 +99,10 @@ public string GetFullPath()
 			return string.Concat(DirectoryName, Package.DirectorySeparator, GetFileName());
 		}
 
+		/// <summary>
+		/// Returns a string representation of this package entry.
+		/// </summary>
+		/// <returns>A string that represents the current package entry.</returns>
 		public override string ToString()
 		{
 			return $"{GetFullPath()} crc=0x{CRC32:x2} metadatasz={SmallData.Length} fnumber={ArchiveIndex} ofs=0x{Offset:x2} sz={Length}";

ValvePak/ValvePak/ValvePak.csproj

@@ -14,6 +14,7 @@
     <AssemblyOriginatorKeyFile>ValvePak.snk</AssemblyOriginatorKeyFile>
     <IsAotCompatible>True</IsAotCompatible>
     <Nullable>enable</Nullable>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
 
   <ItemGroup>