documentation update

Core/Base32.cs

@@ -1,20 +1,42 @@
 namespace Just.Core;
 
+/// <summary>
+/// Encoding options for <see cref="Base32.Encode(ReadOnlySpan{byte}, Base32EncodeOptions)"/>.
+/// </summary>
+[Flags]
 public enum Base32EncodeOptions
 {
+    /// <summary>Standard RFC 4648 encoding (uppercase with padding).</summary>
     None = 0x00,
+    /// <summary>Use lowercase alphabet.</summary>
     LowerCase = 0x01,
+    /// <summary>Omit padding characters.</summary>
     NoPadding = 0x02,
+    /// <summary>Lowercase alphabet without padding (combines <see cref="LowerCase"/> | <see cref="NoPadding"/>).</summary>
     LowerCaseNoPadding = 0x03,
 }
 
+/// <summary>
+/// RFC 4648 Base32 encoder/decoder with span-based APIs.
+/// Uses stack allocation for inputs up to <see cref="MaxBytesStack"/> bytes; heap allocation otherwise.
+/// </summary>
 public static class Base32
 {
+    /// <summary>RFC 4648 Base32 alphabet (uppercase A-Z, 2-7).</summary>
     public const string Alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+    /// <summary>Lowercase variant of the RFC 4648 alphabet.</summary>
     public const string AlphabetLower = "abcdefghijklmnopqrstuvwxyz234567";
+    /// <summary>Padding character (=).</summary>
     public const char Padding = '=';
+    /// <summary>Maximum input byte count that uses stack allocation instead of heap.</summary>
     public const int MaxBytesStack = 250;
 
+    /// <summary>
+    /// Encodes a byte span into a Base32 string.
+    /// </summary>
+    /// <param name="input">The bytes to encode.</param>
+    /// <param name="options">Encoding options (casing, padding). Defaults to standard RFC 4648.</param>
+    /// <returns>The Base32-encoded string.</returns>
     [Pure]
     public static string Encode(ReadOnlySpan<byte> input, Base32EncodeOptions options = Base32EncodeOptions.None)
     {

Core/Base64Url.cs

@@ -2,10 +2,15 @@ using System.Runtime.InteropServices;
 
 namespace Just.Core;
 
+/// <summary>
+/// URL-safe Base64 encoder/decoder for bytes, <see cref="long"/>, and <see cref="Guid"/>.
+/// Uses the standard Base64Url character set (- and _ instead of + and /), padding stripped by default.
+/// </summary>
 public static class Base64Url
 {
     private const char Padding = '=';
 
+    /// <summary>Decodes an 11-character Base64Url string into a <see cref="long"/>.</summary>
     [Pure] public static long DecodeLong(ReadOnlySpan<char> value)
     {
         ArgumentOutOfRangeException.ThrowIfNotEqual(value.Length, 11);
@@ -24,6 +29,7 @@ public static class Base64Url
         return MemoryMarshal.Read<long>(longBytes);
     }
 
+    /// <summary>Decodes a 22-character Base64Url string into a <see cref="Guid"/>.</summary>
     [Pure] public static Guid DecodeGuid(ReadOnlySpan<char> value)
     {
         ArgumentOutOfRangeException.ThrowIfNotEqual(value.Length, 22);
@@ -42,6 +48,7 @@ public static class Base64Url
         return new Guid(guidBytes);
     }
 
+    /// <summary>Decodes a Base64Url string into a byte array.</summary>
     [Pure] public static byte[] Decode(ReadOnlySpan<char> input)
     {
         if (input.IsEmpty) return [];
@@ -53,6 +60,7 @@ public static class Base64Url
         return output[..size].ToArray();
     }
 
+    /// <summary>Decodes a Base64Url string into a pre-allocated byte span. Returns the number of bytes written.</summary>
     [Pure] public static int Decode(ReadOnlySpan<char> value, Span<byte> output)
     {
         var padding = (4 - (value.Length & 3)) & 3;
@@ -72,6 +80,7 @@ public static class Base64Url
         return outputBytes;
     }
 
+    /// <summary>Encodes a <see cref="long"/> into an 11-character Base64Url string.</summary>
     [Pure] public static string Encode(in long id)
     {
         Span<byte> longBytes = stackalloc byte[8];
@@ -84,6 +93,7 @@ public static class Base64Url
         return new string(chars[..^1]);
     }
 
+    /// <summary>Encodes a <see cref="Guid"/> into a 22-character Base64Url string.</summary>
     [Pure] public static string Encode(in Guid id)
     {
         Span<byte> guidBytes = stackalloc byte[16];
@@ -96,6 +106,7 @@ public static class Base64Url
         return new string(chars[..^2]);
     }
 
+    /// <summary>Encodes a byte span into a Base64Url string.</summary>
     [Pure] public static string Encode(ReadOnlySpan<byte> input)
     {
         if (input.IsEmpty) return string.Empty;
@@ -107,6 +118,7 @@ public static class Base64Url
         return new string(output[..strlen]);
     }
 
+    /// <summary>Encodes a byte span into a pre-allocated char span. Returns the number of characters written.</summary>
     [Pure] public static int Encode(ReadOnlySpan<byte> input, Span<char> output)
     {
         if (input.IsEmpty) return 0;

Core/Collections/DataMap.cs

@@ -3,6 +3,11 @@ using System.Runtime.InteropServices;
 
 namespace Just.Core.Collections;
 
+/// <summary>
+/// A 2D grid with lazy min/max caching, cloning, and binary stream serialization.
+/// Requires <typeparamref name="T"/> to support comparison and equality operators.
+/// </summary>
+/// <typeparam name="T">The element type; must implement <c>IComparisonOperators&lt;T, T, bool&gt;</c> and <c>IEqualityOperators&lt;T, T, bool&gt;</c>.</typeparam>
 public class DataMap<T> : Map<T>, IDataMap<T>, ICloneable
     where T : IComparisonOperators<T, T, bool>, IEqualityOperators<T, T, bool>
 {

Core/Collections/IDataMap.cs

@@ -2,6 +2,8 @@ using System.Numerics;
 
 namespace Just.Core.Collections;
 
+/// <summary>Read-only interface for a 2D grid with min/max tracking and cloning.</summary>
+/// <typeparam name="T">The element type; must support comparison and equality operators.</typeparam>
 public interface IDataMap<T> : IMap<T>, ICloneable
     where T : IComparisonOperators<T, T, bool>, IEqualityOperators<T, T, bool>
 {

Core/Collections/IMap.cs

@@ -1,5 +1,7 @@
 namespace Just.Core.Collections;
 
+/// <summary>Read-only interface for a 2D grid with coordinate-based access and enumeration.</summary>
+/// <typeparam name="T">The type of elements in the map.</typeparam>
 public interface IMap<T> : IReadOnlyCollection<MapPoint<T>>
 {
     int Width { get; }

Core/Collections/Map.cs

@@ -2,6 +2,11 @@ using System.Collections;
 
 namespace Just.Core.Collections;
 
+/// <summary>
+/// A 2D grid container providing indexer access, enumeration as <see cref="MapPoint{T}"/> values,
+/// and conversion to a 2D array. Coordinates are clamped to valid ranges.
+/// </summary>
+/// <typeparam name="T">The type of elements in the map.</typeparam>
 public class Map<T> : IMap<T>
 {
     internal readonly T[] _values;

Core/Collections/MapPoint.cs

@@ -1,5 +1,7 @@
 namespace Just.Core.Collections;
 
+/// <summary>A value and its coordinates within a <see cref="IMap{T}"/>.</summary>
+/// <typeparam name="T">The type of the map element.</typeparam>
 public readonly struct MapPoint<T>(T value, int x, int y, IMap<T> map)
 {
     public readonly T Value = value;

Core/Core.csproj

@@ -6,6 +6,8 @@
     <Nullable>enable</Nullable>
     <AssemblyName>Just.Core</AssemblyName>
     <RootNamespace>Just.Core</RootNamespace>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <NoWarn>$(NoWarn);CS1591</NoWarn>
 
     <Description>Small .Net library with useful helper classes, functions and extensions.</Description>
     <PackageTags>extensions;helpers;helper-functions</PackageTags>