Work on TransformHandles docs

Author: Exanite

docs/for-contributors/Generator/generator-mods.md

@@ -599,13 +599,34 @@ The `BoolTypes` property in the configuration should match the configuration use
 
 Mod categories: Transformation
 
+This mod focuses on the transformation of opaque structs into more developer-friendly handle types.
+
+This is done by finding references to empty structs. If all references to the empty struct are done through pointers,
+that struct will be treated as a handle type and transformed.
+
+Empty structs identified as handle types will be transformed in two ways:
+
+1. The struct itself will be transformed to wrap the underlying pointer and have methods/operators added for ease of
+   use.
+
+2. All references to that struct will have their pointer dimension reduced. For example, `VkBuffer**` becomes
+   `VkBuffer*` This is because the mentioned struct transformation means that the innermost pointer dimension is now
+   stored inside the struct.
+
+This mod currently only processes handle types that wrap pointer types. Integer types are not yet supported.
+
 Name affix categories:
 
-- `HandleType` - TODO
+- `HandleType` - This is a suffix added to handle types transformed by `TransformedHandles`. Note that
+  `TransformHandles` only adds the attribute and does not rename the actual handle type. This is so that the rename is
+  deferred until `PrettifyNames` where all renames are done in bulk for performance reasons. This pattern is explained
+  in the [Name Processing - Deferring Renames](name-processing.md#deferring-renames) documentation.
 
 Usage recommendations:
 
-(TODO: To be added)
+This mod should be placed after `ExtractHandles` and `AddOpaqueStructs`. This is because `TransformHandles` relies on
+the previously mentioned mods to add the empty struct types. `TransformHandles` itself does not add new structs, it only
+transforms existing ones that it identifies as a handle type.
 
 ### TransformProperties
 

sources/SilkTouch/SilkTouch/Mods/TransformHandles.cs

@@ -15,16 +15,19 @@
 namespace Silk.NET.SilkTouch.Mods;
 
 /// <summary>
-/// Identifies handle types by finding pointers to empty structs or missing types.
+/// Identifies handle types by finding pointers to empty structs.
 /// In general, a handle type is a struct that wraps an underlying opaque pointer (or some other underlying value).
 /// These handle types are then transformed by making the struct wrap the underlying pointer and
 /// reducing the dimension of pointers referencing that handle type by one.
 /// </summary>
 /// <example>
 /// Given an empty struct, <c>struct VkBuffer</c>, and all usages of that struct are through a pointer,
-/// <c>VkBuffer*</c>, usages of that pointer will be replaced by <c>VkBufferHandle</c>. For a 2-dimensional pointer,
-/// <c>VkBuffer**</c>, the resulting replacement is <c>VkBufferHandle*</c>.
+/// <c>VkBuffer*</c>, usages of that pointer will be replaced by <c>VkBuffer</c>. For a 2-dimensional pointer,
+/// <c>VkBuffer**</c>, the resulting replacement is <c>VkBuffer*</c>.
 /// </example>
+/// <remarks>
+/// The `Handle` suffix is not applied until <see cref="PrettifyNames"/> executes.
+/// </remarks>
 [ModConfiguration<Config>]
 public class TransformHandles(
     IOptionsSnapshot<TransformHandles.Config> config,