From 7b6278daf44b7ffa31e0a1db50890f07394220e5 Mon Sep 17 00:00:00 2001 From: "mika@stocksharp.com" Date: Tue, 18 Feb 2025 13:47:23 +0300 Subject: [PATCH] Xml comments. --- Linq/AsyncEnumerableExtensions.cs | 24 ++++ Linq/ExpressionExtensions.cs | 51 ++++++++ Linq/QueryableExtensions.cs | 209 +++++++++++++++++++++++++++++- Localization/ILocalizer.cs | 8 ++ Localization/LocalizedStrings.cs | 63 +++++++++ Lzma/LzmaStream.cs | 11 ++ Lzma/Probability.cs | 1 + Lzma/SlidingWindow.cs | 6 + Lzma/State.cs | 1 + 9 files changed, 370 insertions(+), 4 deletions(-) diff --git a/Linq/AsyncEnumerableExtensions.cs b/Linq/AsyncEnumerableExtensions.cs index 5ee8656d..736063d5 100644 --- a/Linq/AsyncEnumerableExtensions.cs +++ b/Linq/AsyncEnumerableExtensions.cs @@ -7,8 +7,18 @@ using Ecng.Common; +/// +/// The extensions for . +/// public static class AsyncEnumerableExtensions { + /// + /// Converts the to the array. + /// + /// The type of the elements of the . + /// The enumeration. + /// The cancellation token. + /// The array of the elements of the . public static async ValueTask ToArrayAsync2(this IAsyncEnumerable enu, CancellationToken cancellationToken) { if (enu is null) @@ -22,6 +32,13 @@ public static async ValueTask ToArrayAsync2(this IAsyncEnumerable enu return [.. list]; } + /// + /// Gets the first element of the . + /// + /// The type of the elements of the . + /// The enumeration. + /// The cancellation token. + /// The first element of the . public static async ValueTask FirstAsync2(this IAsyncEnumerable enu, CancellationToken cancellationToken) { if (enu is null) @@ -33,6 +50,13 @@ public static async ValueTask FirstAsync2(this IAsyncEnumerable enu, Ca throw new InvalidOperationException(); } + /// + /// Gets the first element of the or the default value if the enumeration is empty. + /// + /// The type of the elements of the . + /// The enumeration. + /// The cancellation token. + /// The first element of the or the default value if the enumeration is empty. public static async ValueTask FirstOrDefaultAsync2(this IAsyncEnumerable enu, CancellationToken cancellationToken) { if (enu is null) diff --git a/Linq/ExpressionExtensions.cs b/Linq/ExpressionExtensions.cs index 7388f923..a1597b4e 100644 --- a/Linq/ExpressionExtensions.cs +++ b/Linq/ExpressionExtensions.cs @@ -7,11 +7,25 @@ using Ecng.Common; + /// + /// The extensions for . + /// public static class ExpressionExtensions { + /// + /// Gets the constant value from the expression. + /// + /// The type of the constant value. + /// The expression. + /// The constant value. public static T GetConstant(this Expression e) => ((ConstantExpression)e).Value.To(); + /// + /// Evaluates the expression and returns its value. + /// + /// The expression to evaluate. + /// The evaluated value. public static object Evaluate(this Expression e) { //A little optimization for constant expressions @@ -21,6 +35,12 @@ public static object Evaluate(this Expression e) return Expression.Lambda(e).Compile().DynamicInvoke(); } + /// + /// Replaces the source provider in the expression with the specified query provider. + /// + /// The expression to modify. + /// The query provider to set. + /// Thrown when expression or provider is null. public static void ReplaceSource(this Expression expression, IQueryProvider provider) { if (expression is null) @@ -36,6 +56,11 @@ public static void ReplaceSource(this Expression expression, IQueryProvider prov field.SetValue(expression, provider); } + /// + /// Removes quote expressions from the given expression. + /// + /// The expression to process. + /// The unquoted expression. public static Expression StripQuotes(this Expression e) { while (e.NodeType == ExpressionType.Quote) @@ -46,6 +71,13 @@ public static Expression StripQuotes(this Expression e) return e; } + /// + /// Gets the value of the specified member from the given instance. + /// + /// The member whose value to retrieve. + /// The object instance from which to retrieve the value. + /// The value of the member. + /// Thrown when the member type is not supported. public static object GetMemberValue(this MemberInfo member, object instance) { if (member is PropertyInfo pi) @@ -56,6 +88,11 @@ public static object GetMemberValue(this MemberInfo member, object instance) throw new NotSupportedException(); } + /// + /// Retrieves the innermost member in a nested member expression. + /// + /// The member expression to process. + /// The innermost member expression. public static MemberExpression GetInnerMember(this MemberExpression exp) { if (exp.Expression is MemberExpression d) @@ -64,6 +101,14 @@ public static MemberExpression GetInnerMember(this MemberExpression exp) return exp; } + /// + /// Evaluates the expression and returns its value as the specified type. + /// + /// The type to convert the evaluated value to. + /// The expression to evaluate. + /// The evaluated value converted to the specified type. + /// Thrown when the expression is null. + /// Thrown when the expression type is not supported. public static TValue GetValue(this Expression exp) { if (exp is null) @@ -77,6 +122,12 @@ public static TValue GetValue(this Expression exp) throw new ArgumentOutOfRangeException(exp.NodeType.ToString()); } + /// + /// Converts the given expression type to its equivalent . + /// + /// The expression type. + /// The corresponding . + /// Thrown when the expression type has no corresponding operator. public static ComparisonOperator ToOperator(this ExpressionType type) { return type switch diff --git a/Linq/QueryableExtensions.cs b/Linq/QueryableExtensions.cs index d1b405d1..88f11013 100644 --- a/Linq/QueryableExtensions.cs +++ b/Linq/QueryableExtensions.cs @@ -9,8 +9,22 @@ using Ecng.Common; + /// + /// Provides extension methods for to support asynchronous operations and dynamic ordering. + /// + /// + /// This class includes methods to perform operations such as SkipLong, AnyAsync, FirstOrDefaultAsync, CountAsync, and ToArrayAsync. + /// Furthermore, it provides dynamic ordering methods to order the results by property names. + /// public static class QueryableExtensions { + /// + /// Skips the specified number of elements in the source sequence. + /// + /// The type of the elements. + /// The source queryable sequence. + /// The number of elements to skip. + /// An that contains the elements that occur after the specified number of elements. public static IQueryable SkipLong(this IQueryable source, long count) { if (source is null) @@ -24,9 +38,23 @@ public static IQueryable SkipLong(this IQueryable source, long count) )); } + /// + /// Asynchronously determines whether a sequence contains any elements. + /// + /// The type of the elements. + /// The source queryable sequence. + /// A token to monitor for cancellation requests. + /// A representing the asynchronous operation. The task result contains true if the sequence contains any elements; otherwise, false. public static async ValueTask AnyAsync(this IQueryable source, CancellationToken cancellationToken) => await source.FirstOrDefaultAsync(cancellationToken) is not null; + /// + /// Asynchronously returns the first element of a sequence, or a default value if the sequence contains no elements. + /// + /// The type of the elements. + /// The source queryable sequence. + /// A token to monitor for cancellation requests. + /// A representing the asynchronous operation. The task result contains the first element in the sequence or a default value if no element is found. public static ValueTask FirstOrDefaultAsync(this IQueryable source, CancellationToken cancellationToken) => source.Provider.Execute>( Expression.Call( @@ -39,15 +67,47 @@ public static ValueTask FirstOrDefaultAsync(this IQueryable source, Can ) ); + /// + /// Dynamically orders the elements of a sequence in ascending order based on a property name. + /// + /// The type of the elements. + /// The source queryable sequence. + /// The property name to order by. + /// If set to true, ignores case during property name comparison. + /// An whose elements are sorted according to the specified property. public static IOrderedQueryable OrderBy(this IQueryable source, string propertyName, bool ignoreCase) => ApplyOrder(source, propertyName, ignoreCase, nameof(OrderBy)); + /// + /// Dynamically orders the elements of a sequence in descending order based on a property name. + /// + /// The type of the elements. + /// The source queryable sequence. + /// The property name to order by. + /// If set to true, ignores case during property name comparison. + /// An whose elements are sorted in descending order according to the specified property. public static IOrderedQueryable OrderByDescending(this IQueryable source, string propertyName, bool ignoreCase) => ApplyOrder(source, propertyName, ignoreCase, nameof(OrderByDescending)); + /// + /// Dynamically performs a subsequent ordering of the elements of a sequence in ascending order based on a property name. + /// + /// The type of the elements. + /// An ordered queryable sequence. + /// The property name to order by. + /// If set to true, ignores case during property name comparison. + /// An whose elements are further sorted according to the specified property. public static IOrderedQueryable ThenBy(this IOrderedQueryable source, string propertyName, bool ignoreCase) => ApplyOrder(source, propertyName, ignoreCase, nameof(ThenBy)); + /// + /// Dynamically performs a subsequent ordering of the elements of a sequence in descending order based on a property name. + /// + /// The type of the elements. + /// An ordered queryable sequence. + /// The property name to order by. + /// If set to true, ignores case during property name comparison. + /// An whose elements are further sorted in descending order according to the specified property. public static IOrderedQueryable ThenByDescending(this IOrderedQueryable source, string propertyName, bool ignoreCase) => ApplyOrder(source, propertyName, ignoreCase, nameof(ThenByDescending)); @@ -89,6 +149,13 @@ private static IOrderedQueryable ApplyOrder(this IQueryable source, str return (IOrderedQueryable)result; } + /// + /// Asynchronously counts the number of elements in a sequence. + /// + /// The type of the elements. + /// The source queryable sequence. + /// A token to monitor for cancellation requests. + /// A representing the asynchronous operation. The task result contains the count of elements. public static ValueTask CountAsync(this IQueryable source, CancellationToken cancellationToken) { if (source is null) @@ -102,6 +169,13 @@ public static ValueTask CountAsync(this IQueryable source, Cancellat )); } + /// + /// Asynchronously creates an array from a sequence. + /// + /// The type of the elements. + /// The source queryable sequence. + /// A token to monitor for cancellation requests. + /// A representing the asynchronous operation. The task result contains an array that holds the elements from the sequence. public static ValueTask ToArrayAsync(this IQueryable source, CancellationToken cancellationToken) { if (source is null) @@ -116,40 +190,167 @@ public static ValueTask ToArrayAsync(this IQueryable source, Cancella #region Helper methods to obtain MethodInfo in a safe way -#pragma warning disable IDE0051 // Remove unused private members + /// + /// Retrieves the for the specified delegate. + /// + /// The type of the delegate parameter. + /// The return type of the delegate. + /// The delegate to obtain the method information from. + /// A parameter used only for type inference. + /// The of the delegate. public static MethodInfo GetMethodInfo(Func f, T1 unused1) => f.Method; + /// + /// Retrieves the for the specified delegate. + /// + /// The type of the first delegate parameter. + /// The type of the second delegate parameter. + /// The return type of the delegate. + /// The delegate to obtain the method information from. + /// A parameter used only for type inference. + /// A parameter used only for type inference. + /// The of the delegate. public static MethodInfo GetMethodInfo(Func f, T1 unused1, T2 unused2) => f.Method; + /// + /// Retrieves the for the specified delegate. + /// + /// The type of the first delegate parameter. + /// The type of the second delegate parameter. + /// The type of the third delegate parameter. + /// The return type of the delegate. + /// The delegate to obtain the method information from. + /// A parameter used only for type inference. + /// A parameter used only for type inference. + /// A parameter used only for type inference. + /// The of the delegate. public static MethodInfo GetMethodInfo(Func f, T1 unused1, T2 unused2, T3 unused3) => f.Method; + /// + /// Retrieves the for the specified delegate. + /// + /// The type of the first delegate parameter. + /// The type of the second delegate parameter. + /// The type of the third delegate parameter. + /// The type of the fourth delegate parameter. + /// The return type of the delegate. + /// The delegate to obtain the method information from. + /// A parameter used only for type inference. + /// A parameter used only for type inference. + /// A parameter used only for type inference. + /// A parameter used only for type inference. + /// The of the delegate. public static MethodInfo GetMethodInfo(Func f, T1 unused1, T2 unused2, T3 unused3, T4 unused4) => f.Method; + /// + /// Retrieves the for the specified delegate. + /// + /// The type of the first delegate parameter. + /// The type of the second delegate parameter. + /// The type of the third delegate parameter. + /// The type of the fourth delegate parameter. + /// The type of the fifth delegate parameter. + /// The return type of the delegate. + /// The delegate to obtain the method information from. + /// A parameter used only for type inference. + /// A parameter used only for type inference. + /// A parameter used only for type inference. + /// A parameter used only for type inference. + /// A parameter used only for type inference. + /// The of the delegate. public static MethodInfo GetMethodInfo(Func f, T1 unused1, T2 unused2, T3 unused3, T4 unused4, T5 unused5) => f.Method; - public static MethodInfo GetMethodInfo(Func f, T1 unused1, T2 unused2, T3 unused3, T4 unused4, T5 unused5, T6 unused6) - => f.Method; - + /// + /// Retrieves the for the specified delegate. + /// + /// The type of the delegate parameter. + /// The delegate to obtain the method information from. + /// The of the delegate. public static MethodInfo GetMethodInfo(Action f) => f.Method; + /// + /// Retrieves the for the specified delegate. + /// + /// The type of the first delegate parameter. + /// The type of the second delegate parameter. + /// The delegate to obtain the method information from. + /// A parameter used only for type inference. + /// A parameter used only for type inference. + /// The of the delegate. public static MethodInfo GetMethodInfo(Action f, T1 unused1, T2 unused2) => f.Method; + /// + /// Retrieves the for the specified delegate. + /// + /// The type of the first delegate parameter. + /// The type of the second delegate parameter. + /// The type of the third delegate parameter. + /// The delegate to obtain the method information from. + /// A parameter used only for type inference. + /// A parameter used only for type inference. + /// A parameter used only for type inference. + /// The of the delegate. public static MethodInfo GetMethodInfo(Action f, T1 unused1, T2 unused2, T3 unused3) => f.Method; + /// + /// Retrieves the for the specified delegate. + /// + /// The type of the first delegate parameter. + /// The type of the second delegate parameter. + /// The type of the third delegate parameter. + /// The type of the fourth delegate parameter. + /// The delegate to obtain the method information from. + /// A parameter used only for type inference. + /// A parameter used only for type inference. + /// A parameter used only for type inference. + /// A parameter used only for type inference. + /// The of the delegate. public static MethodInfo GetMethodInfo(Action f, T1 unused1, T2 unused2, T3 unused3, T4 unused4) => f.Method; + /// + /// Retrieves the for the specified delegate. + /// + /// The type of the first delegate parameter. + /// The type of the second delegate parameter. + /// The type of the third delegate parameter. + /// The type of the fourth delegate parameter. + /// The type of the fifth delegate parameter. + /// The delegate to obtain the method information from. + /// A parameter used only for type inference. + /// A parameter used only for type inference. + /// A parameter used only for type inference. + /// A parameter used only for type inference. + /// A parameter used only for type inference. + /// The of the delegate. public static MethodInfo GetMethodInfo(Action f, T1 unused1, T2 unused2, T3 unused3, T4 unused4, T5 unused5) => f.Method; + /// + /// Retrieves the for the specified delegate. + /// + /// The type of the first delegate parameter. + /// The type of the second delegate parameter. + /// The type of the third delegate parameter. + /// The type of the fourth delegate parameter. + /// The type of the fifth delegate parameter. + /// The type of the sixth delegate parameter. + /// The delegate to obtain the method information from. + /// A parameter used only for type inference. + /// A parameter used only for type inference. + /// A parameter used only for type inference. + /// A parameter used only for type inference. + /// A parameter used only for type inference. + /// A parameter used only for type inference. + /// The of the delegate. public static MethodInfo GetMethodInfo(Action f, T1 unused1, T2 unused2, T3 unused3, T4 unused4, T5 unused5, T6 unused6) => f.Method; #pragma warning restore IDE0051 // Remove unused private members diff --git a/Localization/ILocalizer.cs b/Localization/ILocalizer.cs index 159bf26a..0b93817c 100644 --- a/Localization/ILocalizer.cs +++ b/Localization/ILocalizer.cs @@ -1,6 +1,14 @@ namespace Ecng.Localization; +/// +/// The interface for localizing strings. +/// public interface ILocalizer { + /// + /// Localizes the string. + /// + /// The string to localize on English. + /// The localized string. public string Localize(string enStr); } \ No newline at end of file diff --git a/Localization/LocalizedStrings.cs b/Localization/LocalizedStrings.cs index 7dc1f583..2c3fa28b 100644 --- a/Localization/LocalizedStrings.cs +++ b/Localization/LocalizedStrings.cs @@ -2,38 +2,101 @@ using Ecng.Common; +/// +/// The localized strings. +/// public static class LocalizedStrings { + /// + /// The localizer. + /// public static ILocalizer Localizer { get; set; } + /// + /// public const string InheritedKey = nameof(Inherited); + /// + /// public const string VerboseKey = nameof(Verbose); + /// + /// public const string DebugKey = nameof(Debug); + /// + /// public const string InfoKey = nameof(Info); + /// + /// public const string WarningsKey = nameof(Warnings); + /// + /// public const string ErrorsKey = nameof(Errors); + /// + /// public const string OffKey = nameof(Off); + /// + /// public const string IdKey = nameof(Id); + /// + /// public const string LoggingKey = nameof(Logging); + /// + /// public const string NameKey = nameof(Name); + /// + /// public const string LogSourceNameKey = nameof(LogSourceName); + /// + /// public const string LogLevelKey = nameof(LogLevel); + /// + /// public const string LogLevelDescKey = nameof(LogLevelDesc); + /// + /// public static string Inherited => Localize(nameof(Inherited)); + /// + /// public static string Verbose => Localize(nameof(Verbose)); + /// + /// public static string Debug => Localize(nameof(Debug)); + /// + /// public static string Info => Localize(nameof(Info)); + /// + /// public static string Warnings => Localize(nameof(Warnings)); + /// + /// public static string Errors => Localize(nameof(Errors)); + /// + /// public static string Off => Localize(nameof(Off)); + /// + /// public static string Id => Localize(nameof(Id)); + /// + /// public static string Logging => Localize(nameof(Logging)); + /// + /// public static string Name => Localize(nameof(Name)); + /// + /// public static string LogSourceName => Localize(nameof(LogSourceName)); + /// + /// public static string LogLevel => Localize(nameof(LogLevel)); + /// + /// public static string LogLevelDesc => Localize(nameof(LogLevelDesc)); + /// + /// Localizes the string. + /// + /// The string to localize on English. + /// The localized string. public static string Localize(this string enStr) => (Localizer?.Localize(enStr)).IsEmpty(enStr); } \ No newline at end of file diff --git a/Lzma/LzmaStream.cs b/Lzma/LzmaStream.cs index 4175a7f5..3e3c78ba 100644 --- a/Lzma/LzmaStream.cs +++ b/Lzma/LzmaStream.cs @@ -102,11 +102,22 @@ public LzmaStream(Stream stream, CompressionMode mode, bool leaveOpen) } } + /// + /// Creates a new in decompression mode. + /// + /// The stream to read from or write to. + /// + /// true to leave the stream open after the object is disposed; otherwise, false. public LzmaStream(Stream stream, CompressionLevel level, bool leaveOpen) : this(stream, CompressionMode.Compress, leaveOpen) { } + /// + /// Creates a new and initializes it with the specified properties. + /// + /// The stream to read from or write to. + /// The encoder properties. public LzmaStream(Stream stream, EncoderProperties properties) : this(stream, CompressionMode.Compress, false) { diff --git a/Lzma/Probability.cs b/Lzma/Probability.cs index 0d32cf63..ef0a5ce1 100644 --- a/Lzma/Probability.cs +++ b/Lzma/Probability.cs @@ -147,6 +147,7 @@ public void Decrement() this.Value = (ushort)(this.Value - (this.Value >> MoveBits)); } + /// public override string ToString() { return $"{(float)this.Value / MaxValue * 100.0f:0.0}% ({this.Value})"; diff --git a/Lzma/SlidingWindow.cs b/Lzma/SlidingWindow.cs index 2f96aeb0..c51782f5 100644 --- a/Lzma/SlidingWindow.cs +++ b/Lzma/SlidingWindow.cs @@ -346,6 +346,12 @@ public uint GetMatchLength(uint originalPos, uint matchPos, uint maxLength) return maxLength - len; } + /// + /// Gets the distance between two positions. + /// + /// + /// + /// [MethodImpl(MethodImplOptions.AggressiveInlining)] public uint GetDistance(uint originalPos, uint matchPos) { diff --git a/Lzma/State.cs b/Lzma/State.cs index 5925ad98..5ef5e8ad 100644 --- a/Lzma/State.cs +++ b/Lzma/State.cs @@ -76,6 +76,7 @@ public void UpdateShortRep() this.Value = this.Value < 7u ? 9u : 11u; } + /// public override string ToString() { return this.Value.ToString(System.Globalization.CultureInfo.InvariantCulture);