Improve some xmldocs

Author: xPaw

ValveKeyValue/ValveKeyValue/IIncludedFileLoader.cs

@@ -1,7 +1,9 @@
 namespace ValveKeyValue
 {
     /// <summary>
-    /// Provides a way to open any file referenced with <c>#include</c> or <c>#base</c>.
+    /// Provides a way to open any file referenced with <c>#include</c> or <c>#base</c> in a KV1 file.
+    /// <c>#include</c> appends the included keys into the current block.
+    /// <c>#base</c> loads a base file whose keys are recursively merged into the current file.
     /// </summary>
     public interface IIncludedFileLoader
     {

ValveKeyValue/ValveKeyValue/KVDocument.cs

@@ -1,12 +1,12 @@
 namespace ValveKeyValue
 {
     /// <summary>
-    /// Represents a KeyValue document with a root name and header.
+    /// Represents a KeyValue document with a root key name and an optional header.
     /// </summary>
     public class KVDocument : KVObject
     {
         /// <summary>
-        /// Gets the header of this document containing encoding and format identifiers.
+        /// Gets the header containing encoding and format identifiers, or <c>null</c> for KV1 documents.
         /// </summary>
         public KVHeader Header { get; }
 

ValveKeyValue/ValveKeyValue/KVHeader.cs

@@ -4,16 +4,17 @@ namespace ValveKeyValue
 {
     /// <summary>
     /// Represents the header of a KeyValues3 document containing encoding and format identifiers.
+    /// KV3 uses GUIDs instead of version integers to uniquely identify formats even across branched codebases.
     /// </summary>
     public class KVHeader
     {
         /// <summary>
-        /// Gets or sets the encoding identifier.
+        /// Gets or sets the encoding identifier (e.g. text, binary, binary block-compressed).
         /// </summary>
         public KV3ID Encoding { get; set; }
 
         /// <summary>
-        /// Gets or sets the format identifier.
+        /// Gets or sets the format identifier describing how the data should be interpreted.
         /// </summary>
         public KV3ID Format { get; set; }
     }

ValveKeyValue/ValveKeyValue/KVSerializationFormat.cs

@@ -7,6 +7,7 @@ public enum KVSerializationFormat
     {
         /// <summary>
         /// KeyValues 1 textual format. Used often in Steam and the Source engine.
+        /// Supports <c>#include</c>, <c>#base</c> directives and conditional expressions (e.g. <c>[$WIN32]</c>).
         /// </summary>
         KeyValues1Text,
 

ValveKeyValue/ValveKeyValue/KVSerializer.cs

@@ -9,7 +9,7 @@
 namespace ValveKeyValue
 {
     /// <summary>
-    /// Helper class to easily deserialize KeyValue objects.
+    /// Helper class to serialize and deserialize KeyValue objects.
     /// </summary>
     public class KVSerializer
     {

ValveKeyValue/ValveKeyValue/KVSerializerOptions.cs

@@ -3,7 +3,7 @@
 namespace ValveKeyValue
 {
     /// <summary>
-    /// Options to use when deserializing a KeyValues file.
+    /// Options to use when serializing or deserializing a KeyValues file.
     /// </summary>
     public sealed class KVSerializerOptions
     {

ValveKeyValue/ValveKeyValue/KVValueType.cs

@@ -11,17 +11,17 @@ public enum KVValueType
         Null,
 
         /// <summary>
-        /// This <see cref="KVObject"/> represents a collection of child <see cref="KVObject"/>s.
+        /// This <see cref="KVObject"/> represents a collection of named key-value pairs (like a dictionary or table).
         /// </summary>
         Collection,
 
         /// <summary>
-        /// This <see cref="KVObject"/> represents an array of child <see cref="KVObject"/>s.
+        /// This <see cref="KVObject"/> represents an ordered array of unnamed child <see cref="KVObject"/>s.
         /// </summary>
         Array,
 
         /// <summary>
-        /// This <see cref="KVObject"/> represents a blob of binary bytes.
+        /// This <see cref="KVObject"/> represents a binary blob (raw byte data).
         /// </summary>
         BinaryBlob,
 

ValveKeyValue/ValveKeyValue/KeyValues3/Encoding.cs

@@ -5,10 +5,10 @@ namespace ValveKeyValue.KeyValues3
     /// </summary>
     public static class Encoding
     {
-        /// <summary>Automatic binary encoding selection.</summary>
+        /// <summary>Automatic binary encoding selection. Chooses the best binary encoding at write time.</summary>
         public static Guid BinaryAuto { get; } = new(new byte[] { 0xE6, 0x09, 0xB1, 0x6E, 0x85, 0x6B, 0x83, 0x45, 0xA3, 0x12, 0x70, 0x3A, 0x6E, 0x04, 0x06, 0x8C });
 
-        /// <summary>Block-compressed binary encoding.</summary>
+        /// <summary>Block-compressed binary encoding using Valve's custom LZ77-style block compression.</summary>
         public static Guid BinaryBlockCompressed { get; } = new(new byte[] { 0x46, 0x1A, 0x79, 0x95, 0xBC, 0x95, 0x6C, 0x4F, 0xA7, 0x0B, 0x05, 0xBC, 0xA1, 0xB7, 0xDF, 0xD2 });
 
         /// <summary>LZ4-compressed binary encoding.</summary>
@@ -17,10 +17,10 @@ public static class Encoding
         /// <summary>Zstandard-compressed binary encoding.</summary>
         public static Guid BinaryZstd { get; } = new(new byte[] { 0x00, 0x0A, 0x62, 0x6F, 0xF0, 0xFE, 0x05, 0x43, 0xA3, 0x5F, 0x04, 0x23, 0x46, 0xB1, 0xDB, 0x29 });
 
-        /// <summary>Uncompressed binary encoding.</summary>
+        /// <summary>Uncompressed binary encoding. Data is stored as-is with a string table and typed values.</summary>
         public static Guid Binary { get; } = new(new byte[] { 0x00, 0x05, 0x86, 0x1B, 0xD8, 0xF7, 0xC1, 0x40, 0xAD, 0x82, 0x75, 0xA4, 0x82, 0x67, 0xE7, 0x14 });
 
-        /// <summary>Text encoding.</summary>
+        /// <summary>Human-readable text encoding with an XML-style comment header.</summary>
         public static Guid Text { get; } = new(new byte[] { 0x3C, 0x7F, 0x1C, 0xE2, 0x33, 0x8A, 0xC5, 0x41, 0x99, 0x77, 0xA7, 0x6D, 0x3A, 0x32, 0xAA, 0x0D });
     }
 }

ValveKeyValue/ValveKeyValue/KeyValues3/Format.cs

@@ -5,7 +5,7 @@ namespace ValveKeyValue.KeyValues3
     /// </summary>
     public static class Format
     {
-        /// <summary>Generic format.</summary>
+        /// <summary>Generic format for arbitrary data, with no assumptions about how the data will be used.</summary>
         public static Guid Generic { get; } = new(new byte[] { 0x7C, 0x16, 0x12, 0x74, 0xE9, 0x06, 0x98, 0x46, 0xAF, 0xF2, 0xE6, 0x3E, 0xB5, 0x90, 0x37, 0xE7 });
     }
 }