Add more xmldoc

Updated PIDIV tests to use IV32 rather than IV sequence checks. Now marked as Obsolete to prevent myself from reusing PKM.IVs getter :)

PKHeX.Core/Game/Enums/Nature.cs

@@ -58,6 +58,9 @@ public static class NatureUtil
     /// <summary>
     /// Checks if the provided <see cref="value"/> is a possible mint nature.
     /// </summary>
+    /// <remarks>
+    /// The only valid mint natures are those which have a stat amp applied, or neutral nature being Serious.
+    /// </remarks>
     public static bool IsMint(this Nature value) => (value.IsFixed() && (byte)value % 6 != 0) || value == Nature.Serious;
 
     /// <summary>

PKHeX.Core/Legality/Verifiers/MiscVerifier.cs

@@ -841,13 +841,14 @@ private static bool CheckHeightWeightOdds(IEncounterTemplate enc)
         return true;
     }
 
-    private void VerifyStatNature(LegalityAnalysis data, PKM pk)
+    private void VerifyStatNature<T>(LegalityAnalysis data, T pk) where T : PKM
     {
-        var sn = (byte)pk.StatNature;
-        if (sn == (byte)pk.Nature)
+        // No encounters innately come with a different Stat Nature...
+        // If it matches the Nature, it is valid. If it doesn't, it should be one of the mint natures.
+        var statNature = pk.StatNature;
+        if (statNature == pk.Nature)
             return;
-        // Only allow Serious nature (12); disallow all other neutral natures.
-        if (sn != 12 && (sn > 24 || sn % 6 == 0))
+        if (!statNature.IsMint())
             data.AddLine(GetInvalid(LStatNatureInvalid));
     }
 

PKHeX.Core/PKM/PKM.cs

@@ -364,6 +364,7 @@ public int FlawlessIVCount
 
     public int[] IVs
     {
+        [Obsolete($"Use the {nameof(GetIVs)} method with stackalloc to not allocate.")]
         get => [IV_HP, IV_ATK, IV_DEF, IV_SPE, IV_SPA, IV_SPD];
         set => SetIVs(value);
     }

PKHeX.Core/Saves/Substructures/Gen9/DXT1.cs

@@ -3,11 +3,26 @@
 
 namespace PKHeX.Core;
 
+/// <summary>
+/// Provides methods for working with DXT1 compressed texture data, including decompression and size calculations.
+/// </summary>
+/// <remarks>
+/// DXT1 is a lossy compression format commonly used for texture data in graphics applications.
+/// This class includes methods to calculate the decompressed size of a texture and to decompress DXT1-compressed data into raw RGBA pixel data.
+/// </remarks>
 public static class DXT1
 {
     private const int bpp = 4;
+
+    /// <summary>
+    /// Calculates the total decompressed size of an image based on its dimensions.
+    /// </summary>
+    /// <param name="width">The width of the image, in pixels. Must be a positive integer.</param>
+    /// <param name="height">The height of the image, in pixels. Must be a positive integer.</param>
+    /// <returns>The total decompressed size of the image, in bytes.</returns>
     public static int GetDecompressedSize(int width, int height) => bpp * width * height;
 
+    /// <inheritdoc cref="Decompress(ReadOnlySpan{byte}, int, int, Span{byte})"/>
     public static byte[] Decompress(ReadOnlySpan<byte> data, int width, int height)
     {
         var result = new byte[GetDecompressedSize(width, height)];
@@ -15,6 +30,19 @@ public static byte[] Decompress(ReadOnlySpan<byte> data, int width, int height)
         return result;
     }
 
+    /// <summary>
+    /// Decompresses a block-compressed texture into raw pixel data.
+    /// </summary>
+    /// <remarks>The decompressed pixel data is written in RGBA format, with each pixel represented by 4 bytes
+    /// (red, green, blue, and alpha channels). The input data is expected to be in a block-compressed format, where
+    /// each 4x4 pixel block is encoded in 8 bytes.</remarks>
+    /// <param name="data">The input span containing the compressed texture data. The data must be in a block-compressed format.</param>
+    /// <param name="width">The width of the texture in pixels. Must be a multiple of 4.</param>
+    /// <param name="height">The height of the texture in pixels. Must be a multiple of 4.</param>
+    /// <param name="result">
+    /// The output span where the decompressed pixel data will be written.
+    /// The span must have sufficient capacity to hold <paramref name="width"/> × <paramref name="height"/> × 4 bytes.
+    /// </param>
     public static void Decompress(ReadOnlySpan<byte> data, int width, int height, Span<byte> result)
     {
         int blockCountX = width / bpp;

PKHeX.Core/Saves/Substructures/Gen9/PlayerFashionUnlock9.cs

@@ -5,6 +5,9 @@
 
 namespace PKHeX.Core;
 
+/// <summary>
+/// Collection of unlock-able fashion items for the player in Generation 9 games.
+/// </summary>
 public static class PlayerFashionUnlock9
 {
     private static ReadOnlySpan<ushort> Eyewear =>
@@ -127,6 +130,10 @@ public static class PlayerFashionUnlock9
         8076, 8077,
     ];
 
+    /// <summary>
+    /// Adds the specified fashion items to the block data.
+    /// </summary>
+    /// <returns>The number of items added that were not already present.</returns>
     public static int Add(SCBlockAccessor acc, uint key, ReadOnlySpan<ushort> add)
     {
         var block = acc.GetBlock(key);
@@ -136,6 +143,7 @@ public static int Add(SCBlockAccessor acc, uint key, ReadOnlySpan<ushort> add)
 
     private const int SIZE = 8;
 
+    /// <inheritdoc cref="Add(SCBlockAccessor, uint, ReadOnlySpan{ushort})"/>
     public static int Add(Span<byte> data, ReadOnlySpan<ushort> add)
     {
         var missing = new HashSet<ushort>(add.Length);
@@ -173,6 +181,9 @@ private static int AddItems(Span<byte> data, IEnumerable<ushort> missing)
         return added;
     }
 
+    /// <summary>
+    /// Unlocks the fashion items for the player based on the requested gender.
+    /// </summary>
     public static int UnlockBase(SCBlockAccessor acc, byte gender)
     {
         int count = 0;

PKHeX.Core/Saves/Util/BinaryExportSetting.cs

@@ -2,11 +2,34 @@
 
 namespace PKHeX.Core;
 
+/// <summary>
+/// Flags to control the export of binary data.
+/// </summary>
 [Flags]
 public enum BinaryExportSetting
 {
+    /// <summary>
+    /// Export the complete binary file with all sections included.
+    /// </summary>
     None,
+
+    /// <summary>
+    /// Exclude the footer section from the exported file.
+    /// </summary>
     ExcludeFooter = 1 << 0,
+
+    /// <summary>
+    /// Exclude the header section from the exported file.
+    /// </summary>
     ExcludeHeader = 1 << 1,
+
+    /// <summary>
+    /// Do not perform finalization steps when exporting.
+    /// </summary>
+    /// <remarks>
+    /// When this flag is set, the export skips any finalization logic such as updating the header or footer segments.
+    /// The exact steps skipped depend on the file type and export implementation.
+    /// See <see cref="ISaveHandler.Finalize"/> implementations for details.
+    /// </remarks>
     ExcludeFinalize = 1 << 2,
 }

PKHeX.Core/Saves/Util/IGCSaveFile.cs

@@ -1,4 +1,4 @@
-namespace PKHeX.Core;
+namespace PKHeX.Core;
 
 /// <summary>
 /// GameCube save file interface for memory cards.
@@ -13,18 +13,21 @@ public interface IGCSaveFile
 
 public static class GCSaveExtensions
 {
+    private const string gci = ".gci";
+    private const string raw = ".raw";
+
     /// <summary>
     /// Gets an export filter for a GameCube file.
     /// </summary>
     public static string GCFilter(this IGCSaveFile gc)
     {
-        const string regular = "GameCube Save File|*.gci|All Files|*.*";
-        const string memcard = "Memory Card Raw File|*.raw|Memory Card Binary File|*.bin|";
+        const string regular = $"GameCube Save File|*{gci}|All Files|*.*";
+        const string memcard = $"Memory Card Raw File|*{raw}|Memory Card Binary File|*.bin|";
         return gc.MemoryCard is not null ? memcard + regular : regular;
     }
 
     /// <summary>
     /// Gets the export extension for a GameCube file.
     /// </summary>
-    public static string GCExtension(this IGCSaveFile gc) => gc.MemoryCard is not null ? ".raw" : ".gci";
+    public static string GCExtension(this IGCSaveFile gc) => gc.MemoryCard is not null ? raw : gci;
 }

PKHeX.Core/Saves/Util/ILangDeviantSave.cs

@@ -1,8 +1,12 @@
-namespace PKHeX.Core;
+namespace PKHeX.Core;
 
 /// <summary>
 /// <see cref="SaveFile"/> behaves differently for different languages (different structure layout).
 /// </summary>
+/// <remarks>
+/// Save files that behave differently based on language are best to have an entirely separate class implementation,
+/// but lack of complete information necessitates sharing implementations.
+/// </remarks>
 public interface ILangDeviantSave : ISaveFileRevision
 {
     bool Japanese { get; }

PKHeX.Core/Saves/Util/Recognition/SaveHandlerSplitResult.cs

@@ -1,5 +1,14 @@
 namespace PKHeX.Core;
 
+/// <summary>
+/// Represents the result of a save operation split into distinct components.
+/// </summary>
+/// <remarks>This type encapsulates the data, header, and footer segments of a save operation,  along with the
+/// associated save handler responsible for processing the operation.</remarks>
+/// <param name="Data">The main data segment of the save operation, typically containing the core save data.</param>
+/// <param name="Header">The header segment of the save operation, which may contain metadata or other relevant information.</param>
+/// <param name="Footer">The footer segment of the save operation, which may contain additional metadata or checksums.</param>
+/// <param name="Handler">The save handler responsible for processing the save operation, providing methods for recognition and finalization.</param>
 public sealed class SaveHandlerSplitResult(byte[] Data, byte[] Header, byte[] Footer, ISaveHandler Handler)
 {
     public readonly byte[] Header = Header;

PKHeX.Core/Saves/Util/SaveExtensions.cs

@@ -40,7 +40,7 @@ public static bool IsCompatiblePKM(this SaveFile sav, PKM pk)
 
     private static List<string> GetSaveFileErrata(this SaveFile sav, PKM pk, IBasicStrings strings)
     {
-        var errata = new List<string>();
+        var errata = new List<string>(0); // usually nothing wrong, so start with empty list
         ushort held = (ushort)pk.HeldItem;
         if (sav.Generation > 1 && held != 0)
         {

Tests/PKHeX.Core.Tests/PKM/PIDIVTests.cs

@@ -1,5 +1,4 @@
 using System;
-using System.Linq;
 using FluentAssertions;
 using Xunit;
 
@@ -24,7 +23,7 @@ public void PIDIVMatchingTest3()
         var gk1 = new PK3();
         PIDGenerator.SetValuesFromSeed(gk1, ga1.Type, ga1.OriginSeed);
         gk1.PID.Should().Be(pk1.PID);
-        gk1.IVs.SequenceEqual(pk1.IVs).Should().BeTrue();
+        gk1.IV32.Should().Be(pk1.IV32);
     }
 
     [Fact]
@@ -61,7 +60,7 @@ public void PIDIVMatchingTest3MiscCXD()
         var gk3 = new PK3();
         PIDGenerator.SetValuesFromSeed(gk3, PIDType.CXD, pv.OriginSeed);
         gk3.PID.Should().Be(pk3.PID);
-        gk3.IVs.SequenceEqual(pk3.IVs).Should().BeTrue();
+        gk3.IV32.Should().Be(pk3.IV32);
     }
 
     [Fact]
@@ -75,7 +74,7 @@ public void PIDIVMatchingTest3MiscChannel()
         var gkC = new PK3();
         PIDGenerator.SetValuesFromSeed(gkC, PIDType.Channel, pv.OriginSeed);
         gkC.PID.Should().Be(pkC.PID);
-        gkC.IVs.SequenceEqual(pkC.IVs).Should().BeTrue();
+        gkC.IV32.Should().Be(pkC.IV32);
     }
 
     [Fact]
@@ -110,7 +109,7 @@ public void PIDIVMatchingTest3Event()
         var gkRS = new PK3 { TID16 = 30317, SID16 = 00000 };
         PIDGenerator.SetValuesFromSeed(gkRS, PIDType.BACD_S, bfix);
         gkRS.PID.Should().Be(pkRS.PID);
-        gkRS.IVs.SequenceEqual(pkRS.IVs).Should().BeTrue();
+        gkRS.IV32.Should().Be(pkRS.IV32);
 
         // Unrestricted Antishiny nyx
         var nyxUA = new PK3 {PID = 0xBD3DF676, IVs = [00, 15, 05, 04, 21, 05], TID16 = 00080, SID16 = 00000};