All public members covered with docs

Also fixed options for the wrapper for mdb_cursor_put operation flags

Author: ilyalukyanov

src/LightningDB.Tests/CursorTests.cs

@@ -54,7 +54,7 @@ private void PopulateCursorValues()
                 //act
                 foreach (var k in keys)
                 {
-                    cur.Put(k, k, PutOptions.None);
+                    cur.Put(k, k, CursorPutOptions.None);
                 }
             }
         }

src/LightningDB/Converters/ConverterExtensions.cs

@@ -8,19 +8,39 @@ namespace LightningDB.Converters
     /// </summary>
     public static class ConverterExtensions
     {
+        /// <summary>
+        /// Register a converter into bytes.
+        /// </summary>
+        /// <typeparam name="TFrom">Converter's source convertion type</typeparam>
+        /// <param name="store">Target sotre.</param>
+        /// <param name="convert">Convertion lambda</param>
         public static void AddConvertToBytes<TFrom>(this ConverterStore store, Func<LightningDatabase, TFrom, byte[]> convert)
         {
             var converter = new ConvertToBytesInstance<TFrom>(convert);
             store.AddConvertToBytes(converter);
         }
-
+        
+        /// <summary>
+        /// Register a converter from bytes
+        /// </summary>
+        /// <typeparam name="TTo">Converter's target convertion type</typeparam>
+        /// <param name="store">Target store.</param>
+        /// <param name="convert">Convertion lambda.</param>
         public static void AddConvertFromBytes<TTo>(this ConverterStore store, Func<LightningDatabase, byte[], TTo> convert)
         {
             var converter = new ConvertFromBytesInstance<TTo>(convert);
             store.AddConvertFromBytes(converter);
         }
 
-        public static Func<LightningDatabase, byte[], TTo> EnsureCorrectSize<TTo>(this Func<LightningDatabase, byte[], TTo> convert, int? size = null) where TTo : struct
+        /// <summary>
+        /// Return a convertion delegate that first ensures if a size in bytes is correct.
+        /// </summary>
+        /// <typeparam name="TTo">Convertion target type.</typeparam>
+        /// <param name="convert">Basic convertion lambda without size ensurance.</param>
+        /// <param name="size">Explicit size or autodetect if null.</param>
+        /// <returns>A convertion delegate that first ensures if a size in bytes is correct</returns>
+        public static Func<LightningDatabase, byte[], TTo> EnsureCorrectSize<TTo>(this Func<LightningDatabase, byte[], TTo> convert, int? size = null) 
+            where TTo : struct
         {
             return (db, x) =>
             {

src/LightningDB/Converters/ConverterStore.cs

@@ -12,26 +12,51 @@ public class ConverterStore
         private readonly IDictionary<Type, object> _convertToBytes = new ConcurrentDictionary<Type, object>(); 
         private readonly IDictionary<Type, object> _convertFromBytes = new ConcurrentDictionary<Type, object>(); 
 
+        /// <summary>
+        /// Register a converter into bytes.
+        /// </summary>
+        /// <typeparam name="TConvertFrom">Converter's source convertion type</typeparam>
+        /// <param name="converter">A converter</param>
         public void AddConvertToBytes<TConvertFrom>(IConvertToBytes<TConvertFrom> converter)
         {
             _convertToBytes.Add(converter.ConvertFromType, converter);
         }
 
+        /// <summary>
+        /// Register a converter from bytes
+        /// </summary>
+        /// <typeparam name="TConvertTo">Converter's target convertion type</typeparam>
+        /// <param name="converter">A converter</param>
         public void AddConvertFromBytes<TConvertTo>(IConvertFromBytes<TConvertTo> converter)
         {
             _convertFromBytes.Add(converter.ConvertFromType, converter);
         }
 
+        /// <summary>
+        /// Gets a converter into bytes for the specified type
+        /// </summary>
+        /// <typeparam name="TConvertFrom">Type to convert from.</typeparam>
+        /// <returns>Corresponsding converter.</returns>
         public IConvertToBytes<TConvertFrom> GetToBytes<TConvertFrom>()
         {
             return (IConvertToBytes<TConvertFrom>) GetToBytes(typeof(TConvertFrom));
         }
 
+        /// <summary>
+        /// Gets a converter from bytes into the specified type.
+        /// </summary>
+        /// <typeparam name="TConvertTo">Type to convert to.</typeparam>
+        /// <returns>Corresponding converter.</returns>
         public IConvertFromBytes<TConvertTo> GetFromBytes<TConvertTo>()
         {
             return (IConvertFromBytes<TConvertTo>) GetFromBytes(typeof(TConvertTo));
         }
 
+        /// <summary>
+        /// Gets a converter into bytes for the specified type
+        /// </summary>
+        /// <param name="fromType">Type to convert from</param>
+        /// <returns>Corresponsding converter</returns>
         public object GetToBytes(Type fromType)
         {
             if (!_convertToBytes.ContainsKey(fromType))
@@ -40,6 +65,11 @@ public object GetToBytes(Type fromType)
             return _convertToBytes[fromType];
         }
 
+        /// <summary>
+        /// Gets a converter from bytes into the specified type.
+        /// </summary>
+        /// <param name="toType">Type to convert to</param>
+        /// <returns>Corresponding converter.</returns>
         public object GetFromBytes(Type toType)
         {
             if (!_convertToBytes.ContainsKey(toType))

src/LightningDB/CursorPutOptions.cs

@@ -0,0 +1,54 @@
+using System;
+
+namespace LightningDB
+{
+    /// <summary>
+    /// Special options for cursor put operation.
+    /// </summary>
+    [Flags]
+    public enum CursorPutOptions
+    {
+        /// <summary>
+        /// No special behavior.
+        /// </summary>
+        None = 0,
+
+        /// <summary>
+        /// Overwrite the current key/data pair
+        /// </summary>
+        Current = 0x40,
+
+        /// <summary>
+        /// Only for MDB_DUPSORT
+        /// For put: don't write if the key and data pair already exist.
+        /// For mdb_cursor_del: remove all duplicate data items.
+        /// </summary>
+        NoDuplicateData = 0x20,
+
+        /// <summary>
+        /// use sorted duplicates
+        /// </summary>
+        DuplicateSort = 0x04,
+
+        /// <summary>
+        /// For put: Don't write if the key already exists.
+        /// </summary>
+        NoOverwrite = 0x10,
+
+        /// <summary>
+        /// For put: Just reserve space for data, don't copy it. Return a pointer to the reserved space.
+        /// </summary>
+        ReserveSpace = 0x10000,
+
+        /// <summary>
+        /// Data is being appended, don't split full pages.
+        /// </summary>
+        AppendData = 0x20000,
+
+        /// <summary>
+        /// Duplicate data is being appended, don't split full pages.
+        /// </summary>
+        AppendDuplicateData = 0x40000
+
+    }
+}

src/LightningDB/LightningCursor.cs

@@ -76,33 +76,55 @@ private void DetachClosingHandler()
         /// </summary>
         public LightningTransaction Transaction { get; private set; }
 
+        /// <summary>
+        /// Position at specified key
+        /// </summary>
+        /// <param name="key">Key</param>
+        /// <returns>Key-value pair for the specified key</returns>
         public KeyValuePair<byte[], byte[]>? MoveTo(byte[] key)
         {
             using (var marshalKey = new MarshalValueStructure(key))
                 return this.Get(CursorOperation.Set, marshalKey.ValueStructure);
         }
 
+        /// <summary>
+        /// Position at key/data pair. Only for MDB_DUPSORT
+        /// </summary>
+        /// <param name="key">Key.</param>
+        /// <param name="value">Value</param>
+        /// <returns>Current key/data pair.</returns>
         public KeyValuePair<byte[], byte[]>? MoveTo(byte[] key, byte[] value)
         {
             using (var marshalKey = new MarshalValueStructure(key))
             using (var marshalValue = new MarshalValueStructure(value))
                 return this.Get(CursorOperation.GetBoth, marshalKey.ValueStructure, marshalValue.ValueStructure);
         }
 
+        /// <summary>
+        /// position at key, nearest data. Only for MDB_DUPSORT
+        /// </summary>
+        /// <param name="key">Key</param>
+        /// <param name="value">Value</param>
+        /// <returns>Nearest value and corresponding key</returns>
         public KeyValuePair<byte[], byte[]>? MoveToFirstValueAfter(byte[] key, byte[] value)
         {
             using (var marshalKey = new MarshalValueStructure(key))
             using (var marshalValue = new MarshalValueStructure(value))
                 return this.Get(CursorOperation.GetBothRange, marshalKey.ValueStructure, marshalValue.ValueStructure);
         }
 
+        /// <summary>
+        /// Position at first key greater than or equal to specified key.
+        /// </summary>
+        /// <param name="key">Key</param>
+        /// <returns>First key-value pair with a key greater than or equal to specified key.</returns>
         public KeyValuePair<byte[], byte[]>? MoveToFirstAfter(byte[] key)
         {
             using(var marshalKey = new MarshalValueStructure(key))
                 return this.Get(CursorOperation.SetRange, marshalKey.ValueStructure);
         }
 
-        //What difference from CursorOperation.Set
+        //What is the difference from CursorOperation.Set?
         /*public KeyValuePair<byte[], byte[]> MoveTo(byte[] key)
         {
             using (var marshalKey = new MarshalValueStructure(key))
@@ -250,7 +272,24 @@ public byte[] MoveNextMultiple()
                 : new KeyValuePair<byte[], byte[]>(keyStruct.ToByteArray(res), valueStruct.ToByteArray(res));
         }
 
-        public void Put(byte[] key, byte[] value, PutOptions options)
+        /// <summary>
+        /// Store by cursor.
+        /// This function stores key/data pairs into the database. 
+        /// If the function fails for any reason, the state of the cursor will be unchanged. 
+        /// If the function succeeds and an item is inserted into the database, the cursor is always positioned to refer to the newly inserted item.
+        /// </summary>
+        /// <param name="key">The key operated on.</param>
+        /// <param name="value">The data operated on.</param>
+        /// <param name="options">
+        /// Options for this operation. This parameter must be set to 0 or one of the values described here.
+        ///     CursorPutOptions.Current - overwrite the data of the key/data pair to which the cursor refers with the specified data item. The key parameter is ignored.
+        ///     CursorPutOptions.NoDuplicateData - enter the new key/data pair only if it does not already appear in the database. This flag may only be specified if the database was opened with MDB_DUPSORT. The function will return MDB_KEYEXIST if the key/data pair already appears in the database.
+        ///     CursorPutOptions.NoOverwrite - enter the new key/data pair only if the key does not already appear in the database. The function will return MDB_KEYEXIST if the key already appears in the database, even if the database supports duplicates (MDB_DUPSORT).
+        ///     CursorPutOptions.ReserveSpace - reserve space for data of the given size, but don't copy the given data. Instead, return a pointer to the reserved space, which the caller can fill in later. This saves an extra memcpy if the data is being generated later.
+        ///     CursorPutOptions.AppendData - append the given key/data pair to the end of the database. No key comparisons are performed. This option allows fast bulk loading when keys are already known to be in the correct order. Loading unsorted keys with this flag will cause data corruption.
+        ///     CursorPutOptions.AppendDuplicateData - as above, but for sorted dup data.
+        /// </param>
+        public void Put(byte[] key, byte[] value, CursorPutOptions options)
         {
             using(var keyMarshalStruct = new MarshalValueStructure(key))
             using (var valueMarshalStruct = new MarshalValueStructure(value))

src/LightningDB/LightningCursorExtensions.cs

@@ -10,13 +10,37 @@ namespace LightningDB
     /// </summary>
     public static class LightningCursorExtensions
     {
+        /// <summary>
+        /// Delete current key/data pair.
+        /// This function deletes the key/data pair to which the cursor refers.
+        /// </summary>
+        /// <param name="cur">A cursor.</param>
+        /// <param name="removeAllDuplicateData">if true, delete all of the data items for the current key. This flag may only be specified if the database was opened with MDB_DUPSORT.</param>
         public static void Delete(this LightningCursor cur, bool removeAllDuplicateData = true)
         {
             cur.Delete(
                 removeAllDuplicateData ? CursorDeleteOption.NoDuplicateData : CursorDeleteOption.None);
         }
 
-        public static void Put<TKey, TValue>(this LightningCursor cur, TKey key, TValue value, PutOptions options = PutOptions.None)
+        /// <summary>
+        /// Store by cursor.
+        /// This function stores key/data pairs into the database. 
+        /// If the function fails for any reason, the state of the cursor will be unchanged. 
+        /// If the function succeeds and an item is inserted into the database, the cursor is always positioned to refer to the newly inserted item.
+        /// </summary>
+        /// <param name="cur">A cursor.</param>
+        /// <param name="key">The key operated on.</param>
+        /// <param name="value">The data operated on.</param>
+        /// <param name="options">
+        /// Options for this operation. This parameter must be set to 0 or one of the values described here. (optional)
+        ///     CursorPutOptions.Current - overwrite the data of the key/data pair to which the cursor refers with the specified data item. The key parameter is ignored.
+        ///     CursorPutOptions.NoDuplicateData - enter the new key/data pair only if it does not already appear in the database. This flag may only be specified if the database was opened with MDB_DUPSORT. The function will return MDB_KEYEXIST if the key/data pair already appears in the database.
+        ///     CursorPutOptions.NoOverwrite - enter the new key/data pair only if the key does not already appear in the database. The function will return MDB_KEYEXIST if the key already appears in the database, even if the database supports duplicates (MDB_DUPSORT).
+        ///     CursorPutOptions.ReserveSpace - reserve space for data of the given size, but don't copy the given data. Instead, return a pointer to the reserved space, which the caller can fill in later. This saves an extra memcpy if the data is being generated later.
+        ///     CursorPutOptions.AppendData - append the given key/data pair to the end of the database. No key comparisons are performed. This option allows fast bulk loading when keys are already known to be in the correct order. Loading unsorted keys with this flag will cause data corruption.
+        ///     CursorPutOptions.AppendDuplicateData - as above, but for sorted dup data.
+        /// </param>
+        public static void Put<TKey, TValue>(this LightningCursor cur, TKey key, TValue value, CursorPutOptions options = CursorPutOptions.None)
         {
             var keyBytes = cur.ToBytes(key);
             var valueBytes = cur.ToBytes(value);