From 7a5150ebb8d55e5e174a6886529309cc42aa1658 Mon Sep 17 00:00:00 2001 From: Havret Date: Wed, 1 Mar 2023 23:31:23 +0100 Subject: [PATCH] Add missing comments to public methods --- .../ProtoBufNetSerializerFactory.cs | 10 ++++- .../ProtobufSerializer.cs | 1 - .../ProtobufSerializerFactory.cs | 6 ++- .../SystemTextJsonSerializer.cs | 1 - .../SystemTextJsonSerializerFactory.cs | 18 ++++++--- src/RocksDb.Extensions/IRocksDbAccessor.cs | 12 +++++- src/RocksDb.Extensions/IRocksDbBuilder.cs | 17 +++++++- src/RocksDb.Extensions/IRocksDbStore.cs | 39 +++++++++++++++++++ src/RocksDb.Extensions/ISerializer.cs | 34 ++++++++++++++++ src/RocksDb.Extensions/ISerializerFactory.cs | 14 +++++++ .../PrimitiveTypesSerializerFactory.cs | 5 +++ src/RocksDb.Extensions/RocksDbExtensions.cs | 11 +++++- src/RocksDb.Extensions/RocksDbOptions.cs | 22 +++++++++-- .../Protos/ProtoNetCacheValue.cs | 2 +- 14 files changed, 174 insertions(+), 18 deletions(-) diff --git a/src/RocksDb.Extensions.ProtoBufNet/ProtoBufNetSerializerFactory.cs b/src/RocksDb.Extensions.ProtoBufNet/ProtoBufNetSerializerFactory.cs index eb01666..9ef4919 100644 --- a/src/RocksDb.Extensions.ProtoBufNet/ProtoBufNetSerializerFactory.cs +++ b/src/RocksDb.Extensions.ProtoBufNet/ProtoBufNetSerializerFactory.cs @@ -1,18 +1,24 @@ -using System; using ProtoBuf.Meta; namespace RocksDb.Extensions.ProtoBufNet; +/// +/// A factory class for creating ProtoBuf-Net serializers. +/// public class ProtoBufNetSerializerFactory : ISerializerFactory { + /// public bool CanCreateSerializer() { + // Checks if ProtoBuf-Net can serialize the specified type. return RuntimeTypeModel.Default.CanSerialize(typeof(T)); } + /// public ISerializer CreateSerializer() { + // Creates an instance of the ProtoBufNetSerializer with the specified type. var type = typeof(ProtoBufNetSerializer<>).MakeGenericType(typeof(T)); return (ISerializer) Activator.CreateInstance(type); } -} +} \ No newline at end of file diff --git a/src/RocksDb.Extensions.Protobuf/ProtobufSerializer.cs b/src/RocksDb.Extensions.Protobuf/ProtobufSerializer.cs index 7ee9fc5..8bf98f6 100644 --- a/src/RocksDb.Extensions.Protobuf/ProtobufSerializer.cs +++ b/src/RocksDb.Extensions.Protobuf/ProtobufSerializer.cs @@ -1,4 +1,3 @@ -using System; using System.Buffers; using Google.Protobuf; diff --git a/src/RocksDb.Extensions.Protobuf/ProtobufSerializerFactory.cs b/src/RocksDb.Extensions.Protobuf/ProtobufSerializerFactory.cs index ff63157..3701a10 100644 --- a/src/RocksDb.Extensions.Protobuf/ProtobufSerializerFactory.cs +++ b/src/RocksDb.Extensions.Protobuf/ProtobufSerializerFactory.cs @@ -1,16 +1,20 @@ -using System; using Google.Protobuf; namespace RocksDb.Extensions.Protobuf; +/// +/// A factory class for creating Google.Protobuf serializers. +/// public class ProtobufSerializerFactory : ISerializerFactory { + /// public bool CanCreateSerializer() { var type = typeof(T); return typeof(IMessage).IsAssignableFrom(type); } + /// public ISerializer CreateSerializer() { var type = typeof(ProtobufSerializer<>).MakeGenericType(typeof(T)); diff --git a/src/RocksDb.Extensions.System.Text.Json/SystemTextJsonSerializer.cs b/src/RocksDb.Extensions.System.Text.Json/SystemTextJsonSerializer.cs index 0b311fc..b06cad2 100644 --- a/src/RocksDb.Extensions.System.Text.Json/SystemTextJsonSerializer.cs +++ b/src/RocksDb.Extensions.System.Text.Json/SystemTextJsonSerializer.cs @@ -1,4 +1,3 @@ -using System; using System.Buffers; using System.Text.Json; diff --git a/src/RocksDb.Extensions.System.Text.Json/SystemTextJsonSerializerFactory.cs b/src/RocksDb.Extensions.System.Text.Json/SystemTextJsonSerializerFactory.cs index 869f4f2..7e8edef 100644 --- a/src/RocksDb.Extensions.System.Text.Json/SystemTextJsonSerializerFactory.cs +++ b/src/RocksDb.Extensions.System.Text.Json/SystemTextJsonSerializerFactory.cs @@ -1,27 +1,33 @@ -using System; using System.Text.Json; namespace RocksDb.Extensions.System.Text.Json; +/// +/// A serializer factory implementation that creates instances of SystemTextJsonSerializer for any type. +/// public class SystemTextJsonSerializerFactory : ISerializerFactory { private readonly JsonSerializerOptions? _options; - + + /// + /// Initializes a new instance of the SystemTextJsonSerializerFactory class with optional JsonSerializerOptions. + /// + /// Optional JsonSerializerOptions to use for serialization. public SystemTextJsonSerializerFactory(JsonSerializerOptions? options = null) { _options = options; } + /// public bool CanCreateSerializer() { return true; } + /// public ISerializer CreateSerializer() { var type = typeof(SystemTextJsonSerializer<>).MakeGenericType(typeof(T)); - return (ISerializer)Activator.CreateInstance(type, _options); + return (ISerializer) Activator.CreateInstance(type, _options); } - - -} +} \ No newline at end of file diff --git a/src/RocksDb.Extensions/IRocksDbAccessor.cs b/src/RocksDb.Extensions/IRocksDbAccessor.cs index 0c23128..f07a75b 100644 --- a/src/RocksDb.Extensions/IRocksDbAccessor.cs +++ b/src/RocksDb.Extensions/IRocksDbAccessor.cs @@ -1,7 +1,15 @@ +using System.ComponentModel; using System.Diagnostics.CodeAnalysis; namespace RocksDb.Extensions; +#pragma warning disable CS1591 + +/// +/// This interface is not intended to be used directly by the clients of the library, +/// as it is used by the to access RocksDB. +/// +[EditorBrowsable(EditorBrowsableState.Never)] public interface IRocksDbAccessor { void Remove(TKey key); @@ -10,4 +18,6 @@ public interface IRocksDbAccessor void PutRange(ReadOnlySpan keys, ReadOnlySpan values); void PutRange(ReadOnlySpan values, Func keySelector); IEnumerable GetAll(); -} \ No newline at end of file +} + +#pragma warning restore CS1591 \ No newline at end of file diff --git a/src/RocksDb.Extensions/IRocksDbBuilder.cs b/src/RocksDb.Extensions/IRocksDbBuilder.cs index 7071921..2523c51 100644 --- a/src/RocksDb.Extensions/IRocksDbBuilder.cs +++ b/src/RocksDb.Extensions/IRocksDbBuilder.cs @@ -1,6 +1,21 @@ namespace RocksDb.Extensions; +/// +/// A builder that can be used to create a RocksDB instance with one or more stores. +/// public interface IRocksDbBuilder { + /// + /// Adds a RocksDB store to the builder for the specified column family. + /// + /// + /// The type of the store's key. + /// The type of the store's value. + /// The type of the store to add. + /// The builder instance for method chaining + /// + /// The type must be a concrete implementation of the abstract class + /// . + /// IRocksDbBuilder AddStore(string columnFamily) where TStore : RocksDbStore; -} +} \ No newline at end of file diff --git a/src/RocksDb.Extensions/IRocksDbStore.cs b/src/RocksDb.Extensions/IRocksDbStore.cs index 43fb016..156f67d 100644 --- a/src/RocksDb.Extensions/IRocksDbStore.cs +++ b/src/RocksDb.Extensions/IRocksDbStore.cs @@ -2,20 +2,59 @@ namespace RocksDb.Extensions; +/// +/// Base class for a RocksDB store that provides basic operations such as add, update, remove, get and get all. +/// +/// The type of the store's keys. +/// The type of the store's values. public abstract class RocksDbStore { private readonly IRocksDbAccessor _rocksDbAccessor; + /// + /// Initializes a new instance of the class with the specified RocksDB accessor. + /// + /// The RocksDB accessor to use for database operations. protected RocksDbStore(IRocksDbAccessor rocksDbAccessor) => _rocksDbAccessor = rocksDbAccessor; + /// + /// Removes the specified key and its associated value from the store. + /// + /// The key to remove. public void Remove(TKey key) => _rocksDbAccessor.Remove(key); + /// + /// Adds or updates the specified key-value pair in the store. + /// + /// The key to add or update. + /// The value to add or update. public void Put(TKey key, TValue value) => _rocksDbAccessor.Put(key, value); + /// + /// Tries to get the value associated with the specified key in the store. + /// + /// The key of the value to get. + /// The value associated with the specified key, if the key is found; otherwise, the default value for the type of the value parameter. + /// true if the key is found; otherwise, false. public bool TryGet(TKey key, [MaybeNullWhen(false)] out TValue value) => _rocksDbAccessor.TryGet(key, out value); + /// + /// Puts the specified keys and values in the store. + /// + /// The keys to put in the store. + /// The values to put in the store. public void PutRange(ReadOnlySpan keys, ReadOnlySpan values) => _rocksDbAccessor.PutRange(keys, values); + + /// + /// Puts the specified values in the store using the specified key selector function to generate keys. + /// + /// The values to put in the store. + /// The function to use to generate keys for the values. public void PutRange(ReadOnlySpan values, Func keySelector) => _rocksDbAccessor.PutRange(values, keySelector); + /// + /// Gets all the values in the store. + /// + /// An enumerable collection of all the values in the store. public IEnumerable GetAll() => _rocksDbAccessor.GetAll(); } diff --git a/src/RocksDb.Extensions/ISerializer.cs b/src/RocksDb.Extensions/ISerializer.cs index 1876d14..ede4cfb 100644 --- a/src/RocksDb.Extensions/ISerializer.cs +++ b/src/RocksDb.Extensions/ISerializer.cs @@ -2,10 +2,44 @@ namespace RocksDb.Extensions; +/// +/// Defines the contract for a serializer that can serialize and deserialize objects of type T to and from a byte buffer. +/// +/// The type of object to be serialized. public interface ISerializer { + /// + /// Attempts to calculate the size in bytes required to serialize the specified object. + /// + /// The object to be serialized. + /// The size of the buffer required to serialize the object. + /// true if the size was calculated successfully; otherwise, false. bool TryCalculateSize(ref T value, out int size); + + /// + /// Serializes the specified object to a byte buffer. + /// + /// The object to serialize. + /// The byte span to write the serialized object to. + /// + /// This method will be used when returns true. + /// void WriteTo(ref T value, ref Span span); + + /// + /// Serializes the specified object to a byte buffer using the provided buffer writer. + /// + /// The object to serialize. + /// The to write the serialized object to. + /// + /// This method will be used when returns false. + /// void WriteTo(ref T value, IBufferWriter buffer); + + /// + /// Deserializes an object from the provided byte span. + /// + /// The byte span containing the serialized object. + /// The deserialized object. T Deserialize(ReadOnlySpan buffer); } diff --git a/src/RocksDb.Extensions/ISerializerFactory.cs b/src/RocksDb.Extensions/ISerializerFactory.cs index a2ea8df..7a220f5 100644 --- a/src/RocksDb.Extensions/ISerializerFactory.cs +++ b/src/RocksDb.Extensions/ISerializerFactory.cs @@ -1,7 +1,21 @@ namespace RocksDb.Extensions; +/// +/// Defines an interface for a serializer factory that can create serializers for a given type. +/// public interface ISerializerFactory { + /// + /// Determines whether this factory can create a serializer for the specified type. + /// + /// The type to create a serializer for. + /// true if this factory can create a serializer for the specified type; otherwise, false. bool CanCreateSerializer(); + + /// + /// Creates a serializer for the specified type. + /// + /// The type to create a serializer for. + /// A serializer for the specified type. ISerializer CreateSerializer(); } diff --git a/src/RocksDb.Extensions/PrimitiveTypesSerializerFactory.cs b/src/RocksDb.Extensions/PrimitiveTypesSerializerFactory.cs index 7369253..48a7b2e 100644 --- a/src/RocksDb.Extensions/PrimitiveTypesSerializerFactory.cs +++ b/src/RocksDb.Extensions/PrimitiveTypesSerializerFactory.cs @@ -3,8 +3,12 @@ namespace RocksDb.Extensions; +/// +/// Factory for creating serializers for primitive types such as int, long, and string. +/// public class PrimitiveTypesSerializerFactory : ISerializerFactory { + /// public bool CanCreateSerializer() { var type = typeof(T); @@ -24,6 +28,7 @@ public bool CanCreateSerializer() return false; } + /// public ISerializer CreateSerializer() { var type = typeof(T); diff --git a/src/RocksDb.Extensions/RocksDbExtensions.cs b/src/RocksDb.Extensions/RocksDbExtensions.cs index 4bc6003..78022a9 100644 --- a/src/RocksDb.Extensions/RocksDbExtensions.cs +++ b/src/RocksDb.Extensions/RocksDbExtensions.cs @@ -3,8 +3,17 @@ namespace RocksDb.Extensions; +/// +/// Extension methods for setting up RocksDB related services in an . +/// public static class RocksDbExtensions { + /// + /// This method adds the necessary services to the dependency injection container required for RocksDB integration. + /// + /// The . + /// A delegate that is used to configure the options for the RocksDB instance. + /// An instance of that can be used to build and configure a RocksDB instance. public static IRocksDbBuilder AddRocksDb(this IServiceCollection services, Action optionsAction) { services.AddOptions(); @@ -12,4 +21,4 @@ public static IRocksDbBuilder AddRocksDb(this IServiceCollection services, Actio services.TryAddSingleton(); return new RocksDbBuilder(services); } -} +} \ No newline at end of file diff --git a/src/RocksDb.Extensions/RocksDbOptions.cs b/src/RocksDb.Extensions/RocksDbOptions.cs index d2b1654..0834043 100644 --- a/src/RocksDb.Extensions/RocksDbOptions.cs +++ b/src/RocksDb.Extensions/RocksDbOptions.cs @@ -1,8 +1,24 @@ namespace RocksDb.Extensions; +/// +/// Represents the configuration options for a RocksDB instance. +/// public class RocksDbOptions { - public string Path { get; set; } - internal List ColumnFamilies { get; } = new(); + /// + /// A string that represents the path to the RocksDB instance on disk. + /// + public string Path { get; set; } = null!; + + /// + /// A list of instances that are used to serialize and deserialize data in the RocksDB instance. + /// + /// + /// At least one serializer factory must be registered before using the RocksDB instance. + /// If no factory can create a serializer for any type defined by any of the registered stores, + /// an will be thrown. + /// public List SerializerFactories { get; } = new(); -} + + internal List ColumnFamilies { get; } = new(); +} \ No newline at end of file diff --git a/test/RocksDb.Extensions.Tests/Protos/ProtoNetCacheValue.cs b/test/RocksDb.Extensions.Tests/Protos/ProtoNetCacheValue.cs index 6ace506..0532fea 100644 --- a/test/RocksDb.Extensions.Tests/Protos/ProtoNetCacheValue.cs +++ b/test/RocksDb.Extensions.Tests/Protos/ProtoNetCacheValue.cs @@ -10,5 +10,5 @@ public class ProtoNetCacheValue public int Id { get; set; } [ProtoMember(2)] - public string Value { get; set; } + public string Value { get; set; } = null!; }