Improve some of the doc comments

Author: CoreyKaylor

src/LightningDB/DatabaseConfiguration.cs

@@ -6,6 +6,10 @@
 
 namespace LightningDB;
 
+/// <summary>
+/// Represents the configuration for a database in the LightningDB library.
+/// Allows setting custom flags and configuring comparer logic for database operations.
+/// </summary>
 public class DatabaseConfiguration
 {
     private IComparer<MDBValue> _comparer;
@@ -16,6 +20,15 @@ public DatabaseConfiguration()
         Flags = DatabaseOpenFlags.None;
     }
 
+    /// <summary>
+    /// Gets or sets the configuration flags used when opening a database.
+    /// </summary>
+    /// <remarks>
+    /// The <see cref="Flags"/> property specifies the behavior of the database based on the combination of
+    /// values from the <see cref="DatabaseOpenFlags"/> enumeration. These flags determine how the database
+    /// should be opened and interacted with, such as creating new databases, sorting duplicates, or using
+    /// integer keys. The default value is <see cref="DatabaseOpenFlags.None"/>.
+    /// </remarks>
     public DatabaseOpenFlags Flags { get; set; }
 
 
@@ -46,11 +59,23 @@ private int IsDuplicate(ref MDBValue left, ref MDBValue right)
         return _duplicatesComparer.Compare(left, right);
     }
 
+    /// <summary>
+    /// Sets a custom comparer for database operations using the specified comparer.
+    /// </summary>
+    /// <param name="comparer">
+    /// The comparer implementation to use for comparing MDBValue objects.
+    /// </param>
     public void CompareWith(IComparer<MDBValue> comparer)
     {
         _comparer = comparer;
     }
 
+    /// <summary>
+    /// Sets a custom comparer for detecting duplicate records in the database.
+    /// </summary>
+    /// <param name="comparer">
+    /// The comparer implementation to use for identifying duplicates between MDBValue objects.
+    /// </param>
     public void FindDuplicatesWith(IComparer<MDBValue> comparer)
     {
         _duplicatesComparer = comparer;

src/LightningDB/EnvironmentConfiguration.cs

@@ -1,32 +1,87 @@
 namespace LightningDB;
 
 /// <summary>
-/// Basic environment configuration
+/// Represents the configuration options for a LightningEnvironment instance.
 /// </summary>
+/// <remarks>
+/// This class enables customization of various environment parameters such as the size of the memory map,
+/// the maximum number of databases, and the maximum number of reader slots. These configurations are applied
+/// to a LightningEnvironment during its creation or initialization.
+/// </remarks>
 public class EnvironmentConfiguration
 {
     private long? _mapSize;
     private int? _maxReaders;
     private int? _maxDatabases;
-        
+
+    /// <summary>
+    /// Gets or sets the size of the memory map (in bytes) for a LightningEnvironment.
+    /// </summary>
+    /// <remarks>
+    /// This property specifies the maximum size of the database file that can be mapped into memory. Adjusting this value
+    /// is critical when working with databases expected to grow over time, as it defines the capacity available for storing data.
+    /// - Increasing the map size allows the database to accommodate more data, but it may consume more virtual memory.
+    /// - Decreasing the map size can restrict database growth or limit memory consumption.
+    /// Changes to the <c>MapSize</c> might require restarting the environment or re-creating it with the new configuration,
+    /// depending on the implementation of the underlying storage environment.
+    /// Use caution when setting this value in applications running in 32-bit processes, as the effective addressable memory
+    /// space is limited. For such scenarios, auto-adjustments may be applied to ensure compatibility.
+    /// </remarks>
     public long MapSize
     {
         get => _mapSize ?? 0;
         set => _mapSize = value;
     }
 
+    /// <summary>
+    /// Gets or sets the maximum number of reader slots available for a LightningEnvironment instance.
+    /// </summary>
+    /// <remarks>
+    /// This property defines the maximum number of simultaneous read transactions that can be performed on the environment.
+    /// - Increasing the value allows for more concurrent read operations, but it may increase resource usage.
+    /// - Decreasing the value limits the number of concurrent reads but may reduce memory consumption.
+    /// Changes to the <c>MaxReaders</c> property must be set before the environment is opened. Attempting to modify this
+    /// property after the environment is already initialized will result in an exception. Adjust this parameter to match
+    /// the requirements of your application's workload and concurrency needs.
+    /// </remarks>
     public int MaxReaders
     {
         get => _maxReaders ?? 0;
         set => _maxReaders = value;
     }
 
+    /// <summary>
+    /// Gets or sets the maximum number of databases that can be opened within a LightningEnvironment instance.
+    /// </summary>
+    /// <remarks>
+    /// This property defines the upper limit on the number of named databases that can be created or opened within the environment.
+    /// - Increasing the maximum database count may allow complex applications to organize data across multiple logical databases.
+    /// - Decreasing the maximum database count can help reduce overhead in environments with constrained resources or simpler use cases.
+    /// Changes to the <c>MaxDatabases</c> property must be configured before the environment is opened. Attempting to modify this
+    /// value after the environment has been initialized will result in an exception. This limitation ensures consistency across
+    /// resources allocated for the environment.
+    /// Configuring the appropriate <c>MaxDatabases</c> value is particularly relevant for applications requiring concurrency or
+    /// multiple named databases.
+    /// </remarks>
     public int MaxDatabases
     {
         get => _maxDatabases ?? 0;
         set => _maxDatabases = value;
     }
 
+    /// <summary>
+    /// Gets or sets a value indicating whether the map size should be automatically reduced
+    /// in 32-bit processes to ensure compatibility with limited addressable memory space.
+    /// </summary>
+    /// <remarks>
+    /// In 32-bit processes, the addressable memory space is constrained, which may lead to issues
+    /// when working with large map sizes. When this property is set to <c>true</c>, the environment
+    /// will automatically adjust the map size to a suitable value (e.g., <c>int.MaxValue</c>) during
+    /// configuration to prevent memory allocation errors or crashes. This adjustment is only applied
+    /// on 32-bit systems and has no effect on 64-bit processes.
+    /// This setting is critical for maintaining stability in environments with constrained memory
+    /// while allowing applications to utilize an appropriate map size without manual intervention.
+    /// </remarks>
     public bool AutoReduceMapSizeIn32BitProcess { get; set; }
 
     internal void Configure(LightningEnvironment env)

src/LightningDB/LightningCursor.cs

@@ -7,7 +7,7 @@
 namespace LightningDB;
 
 /// <summary>
-/// Cursor to iterate over a database
+/// Represents a cursor used to navigate and manipulate records within a database in the context of a transaction.
 /// </summary>
 public class LightningCursor : IDisposable
 {

src/LightningDB/LightningDatabase.cs

@@ -4,7 +4,9 @@
 namespace LightningDB;
 
 /// <summary>
-/// Lightning database.
+/// Represents a database in the Lightning environment, providing mechanisms to perform
+/// various operations such as opening, dropping, and accessing database statistics. Generally,
+/// a database can be reused and rarely needs to be disposed.
 /// </summary>
 public sealed class LightningDatabase : IDisposable
 {

src/LightningDB/LightningEnvironment.cs

@@ -5,7 +5,9 @@
 namespace LightningDB;
 
 /// <summary>
-/// LMDB Environment.
+/// Represents a managed environment for lightning-fast database storage and retrieval. Typically, your application
+/// will have one instance of LightningEnvironment. Also, it is possible for separate processes to read from the
+/// same environment when set to read-only.
 /// </summary>
 public sealed class LightningEnvironment : IDisposable
 {

src/LightningDB/LightningTransaction.cs

@@ -5,7 +5,9 @@
 namespace LightningDB;
 
 /// <summary>
-/// Represents a transaction.
+/// Represents a transaction in the LightningDB environment.
+/// Provides methods for managing database operations within the scope of a transaction, including
+/// database access, key-value storage, and transaction control (commit, abort, etc.).
 /// </summary>
 public sealed class LightningTransaction : IDisposable
 {
@@ -371,7 +373,7 @@ private void Dispose(bool disposing)
     }
 
     /// <summary>
-    /// Dispose this transaction and deallocate all resources associated with it (including databases).
+    /// Dispose this transaction
     /// </summary>
     public void Dispose()
     {