Improve docs.

Ygg01 · Ygg01 · commit 251f15e907a6 · 2024-01-23T21:00:01.000+01:00
diff --git a/Linguini.Bundle/ConcurrentBundle.cs b/Linguini.Bundle/ConcurrentBundle.cs
@@ -13,45 +13,33 @@
 
 namespace Linguini.Bundle
 {
+    /// <summary>
+    /// Represents a thread-safe implementation of the FluentBundle class.
+    ///
+    /// `ConcurrentBundle` implements the <see cref="IReadBundle"/> interface.
+    /// </summary>
     public sealed class ConcurrentBundle : FluentBundle, IEquatable<ConcurrentBundle>
     {
         internal ConcurrentDictionary<string, FluentFunction> Functions = new();
-        private ConcurrentDictionary<string, AstTerm> _terms = new();
-        private ConcurrentDictionary<string, AstMessage> _messages = new();
-
-        public static ConcurrentBundle Thaw(FrozenBundle frozenBundle)
-        {
-            return new ConcurrentBundle
-            {
-                _messages = new ConcurrentDictionary<string, AstMessage>(frozenBundle.Messages),
-                Functions = new ConcurrentDictionary<string, FluentFunction>(frozenBundle.Functions),
-                _terms = new ConcurrentDictionary<string, AstTerm>(frozenBundle.Terms),
-                FormatterFunc = frozenBundle.FormatterFunc,
-                Locales = frozenBundle.Locales,
-                UseIsolating = frozenBundle.UseIsolating,
-                MaxPlaceable = frozenBundle.MaxPlaceable,
-                EnableExtensions = frozenBundle.EnableExtensions,
-                TransformFunc = frozenBundle.TransformFunc,
-                Culture = frozenBundle.Culture
-            };
-        }
+        internal ConcurrentDictionary<string, AstTerm> Terms = new();
+        internal ConcurrentDictionary<string, AstMessage> Messages = new();
 
         /// <inheritdoc />
         protected override void AddMessageOverriding(AstMessage message)
         {
-            _messages[message.GetId()] = message;
+            Messages[message.GetId()] = message;
         }
 
         /// <inheritdoc />
         protected override void AddTermOverriding(AstTerm term)
         {
-            _terms[term.GetId()] = term;
+            Terms[term.GetId()] = term;
         }
 
         /// <inheritdoc />
         protected override bool TryAddTerm(AstTerm term, List<FluentError>? errors)
         {
-            if (_terms.TryAdd(term.GetId(), term)) return true;
+            if (Terms.TryAdd(term.GetId(), term)) return true;
             errors ??= new List<FluentError>();
             errors.Add(new OverrideFluentError(term.GetId(), EntryKind.Term));
             return false;
@@ -60,7 +48,7 @@ protected override bool TryAddTerm(AstTerm term, List<FluentError>? errors)
         /// <inheritdoc />
         protected override bool TryAddMessage(AstMessage message, List<FluentError>? errors)
         {
-            if (_messages.TryAdd(message.GetId(), message)) return true;
+            if (Messages.TryAdd(message.GetId(), message)) return true;
             errors ??= new List<FluentError>();
             errors.Add(new OverrideFluentError(message.GetId(), EntryKind.Message));
             return false;
@@ -89,19 +77,19 @@ public override void AddFunctionUnchecked(string funcName, ExternalFunction flue
         /// <inheritdoc />
         public override bool HasMessage(string identifier)
         {
-            return _messages.ContainsKey(identifier);
+            return Messages.ContainsKey(identifier);
         }
 
         /// <inheritdoc />
         public override bool TryGetAstMessage(string ident, [NotNullWhen(true)] out AstMessage? message)
         {
-            return _messages.TryGetValue(ident, out message);
+            return Messages.TryGetValue(ident, out message);
         }
 
         /// <inheritdoc />
         public override bool TryGetAstTerm(string ident, [NotNullWhen(true)] out AstTerm? term)
         {
-            return _terms.TryGetValue(ident, out term);
+            return Terms.TryGetValue(ident, out term);
         }
 
 
@@ -114,7 +102,7 @@ public override bool TryGetFunction(string funcName, [NotNullWhen(true)] out Flu
         /// <inheritdoc />
         public override IEnumerable<string> GetMessageEnumerable()
         {
-            return _messages.Keys;
+            return Messages.Keys;
         }
 
         /// <inheritdoc />
@@ -126,19 +114,22 @@ public override IEnumerable<string> GetFuncEnumerable()
         /// <inheritdoc />
         public override IEnumerable<string> GetTermEnumerable()
         {
-            return _terms.Keys;
+            return Terms.Keys;
         }
 
+        /// <inheritdoc/>
         internal override IDictionary<string, AstMessage> GetMessagesDictionary()
         {
-            return _messages;
+            return Messages;
         }
 
+        /// <inheritdoc/>
         internal override IDictionary<string, AstTerm> GetTermsDictionary()
         {
-            return _terms;
+            return Terms;
         }
 
+        /// <inheritdoc/>
         internal override IDictionary<string, FluentFunction> GetFunctionDictionary()
         {
             return Functions;
@@ -150,8 +141,8 @@ public override FluentBundle DeepClone()
             return new ConcurrentBundle
             {
                 Functions = new ConcurrentDictionary<string, FluentFunction>(Functions),
-                _terms = new ConcurrentDictionary<string, AstTerm>(_terms),
-                _messages = new ConcurrentDictionary<string, AstMessage>(_messages),
+                Terms = new ConcurrentDictionary<string, AstTerm>(Terms),
+                Messages = new ConcurrentDictionary<string, AstMessage>(Messages),
                 Culture = (CultureInfo)Culture.Clone(),
                 Locales = new List<string>(Locales),
                 UseIsolating = UseIsolating,
@@ -167,8 +158,8 @@ public bool Equals(ConcurrentBundle? other)
         {
             if (ReferenceEquals(null, other)) return false;
             if (ReferenceEquals(this, other)) return true;
-            return base.Equals(other) && Functions.SequenceEqual(other.Functions) && _terms.SequenceEqual(other._terms) &&
-                   _messages.SequenceEqual(other._messages);
+            return base.Equals(other) && Functions.SequenceEqual(other.Functions) && Terms.SequenceEqual(other.Terms) &&
+                   Messages.SequenceEqual(other.Messages);
         }
 
         /// <inheritdoc/>
@@ -180,7 +171,7 @@ public override bool Equals(object? obj)
         /// <inheritdoc/>
         public override int GetHashCode()
         {
-            return HashCode.Combine(base.GetHashCode(), Functions, _terms, _messages);
+            return HashCode.Combine(base.GetHashCode(), Functions, Terms, Messages);
         }
     }
 }
diff --git a/Linguini.Bundle/FrozenBundle.cs b/Linguini.Bundle/FrozenBundle.cs
@@ -115,11 +115,13 @@ internal FrozenBundle(FluentBundle bundle)
             Functions = new Dictionary<string, FluentFunction>(bundle.GetFunctionDictionary());
         }
 #endif
+        /// <inheritdoc/>
         public bool HasMessage(string identifier)
         {
             return Messages.ContainsKey(identifier);
         }
 
+        /// <inheritdoc/>
         public string FormatPattern(Pattern pattern, IDictionary<string, IFluentType>? args,
             [NotNullWhen(false)] out IList<FluentError>? errors)
         {
@@ -129,36 +131,43 @@ public string FormatPattern(Pattern pattern, IDictionary<string, IFluentType>? a
             return value.AsString();
         }
 
+        /// <inheritdoc/>
         public bool TryGetAstMessage(string ident, [NotNullWhen(true)] out AstMessage? message)
         {
             return Messages.TryGetValue(ident, out message);
         }
 
+        /// <inheritdoc/>
         public bool TryGetAstTerm(string ident, [NotNullWhen(true)] out AstTerm? term)
         {
             return Terms.TryGetValue(ident, out term);
         }
 
+        /// <inheritdoc/>
         public bool TryGetFunction(Identifier id, [NotNullWhen(true)] out FluentFunction? function)
         {
             return Functions.TryGetValue(id.ToString(), out function);
         }
 
+        /// <inheritdoc/>
         public bool TryGetFunction(string funcName, [NotNullWhen(true)] out FluentFunction? function)
         {
             return Functions.TryGetValue(funcName, out function);
         }
 
+        /// <inheritdoc/>
         public IEnumerable<string> GetMessageEnumerable()
         {
             return Messages.Keys;
         }
 
+        /// <inheritdoc/>
         public IEnumerable<string> GetFuncEnumerable()
         {
             return Functions.Keys;
         }
 
+        /// <inheritdoc/>
         public IEnumerable<string> GetTermEnumerable()
         {
             return Terms.Keys;
diff --git a/Linguini.Bundle/IReadBundle.cs b/Linguini.Bundle/IReadBundle.cs
@@ -1,4 +1,5 @@
 ﻿using System;
+using System.Collections.Concurrent;
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
 using Linguini.Bundle.Errors;
@@ -8,6 +9,9 @@
 
 namespace Linguini.Bundle
 {
+    /// <summary>
+    /// Represents an interface for reading language bundles.
+    /// </summary>
     public interface IReadBundle
     {
         /// <summary>
@@ -197,8 +201,33 @@ public bool TryGetMessage(string id, string? attribute, IDictionary<string, IFlu
         }
     }
 
+    /// <summary>
+    /// Provides extension methods for working with bundles.
+    /// </summary>
     public static class ReadBundleExtensions
     {
+        /// <summary>
+        /// Thaws a frozen bundle and returns a new instance of a concurrent bundle.
+        /// </summary>
+        /// <param name="frozenBundle">The frozen bundle to thaw.</param>
+        /// <returns>A new instance of a concurrent bundle.</returns>
+        public static ConcurrentBundle Thaw(this FrozenBundle frozenBundle)
+        {
+            return new ConcurrentBundle
+            {
+                Messages = new ConcurrentDictionary<string, AstMessage>(frozenBundle.Messages),
+                Functions = new ConcurrentDictionary<string, FluentFunction>(frozenBundle.Functions),
+                Terms = new ConcurrentDictionary<string, AstTerm>(frozenBundle.Terms),
+                FormatterFunc = frozenBundle.FormatterFunc,
+                Locales = frozenBundle.Locales,
+                UseIsolating = frozenBundle.UseIsolating,
+                MaxPlaceable = frozenBundle.MaxPlaceable,
+                EnableExtensions = frozenBundle.EnableExtensions,
+                TransformFunc = frozenBundle.TransformFunc,
+                Culture = frozenBundle.Culture
+            };
+        }
+        
         /// <summary>
         /// Convenience method for <see cref="IReadBundle.HasAttrMessage"/>
         /// </summary>
@@ -251,8 +280,8 @@ public static bool HasAttrMessage(this IReadBundle bundle, string idWithAttr)
         /// <param name="bundle">The bundle to retrieve the message from.</param>
         /// <param name="msgWithAttr">The message with attribute</param>
         /// <param name="args">Optional arguments to be passed to the attribute message.</param>
-        /// <param name="errors">When this method returns, contains any errors that occured during retrieval, if any.</param>
-        /// <param name="message">When this method returns, contains the retrieved attribute message, if it exists.</param>
+        /// <param name="errors">When this method returns false, contains a list of errors that occurred while trying to retrieve the message; otherwise, null.</param>
+        /// <param name="message">When this method returns true, contains the retrieved message; otherwise, null.</param>
         /// <returns><c>true</c> if the attribute message was successfully retrieved; otherwise, <c>false</c>.</returns>
         public static bool TryGetAttrMessage(this IReadBundle bundle, string msgWithAttr,
             IDictionary<string, IFluentType>? args,
@@ -266,8 +295,8 @@ public static bool TryGetAttrMessage(this IReadBundle bundle, string msgWithAttr
         /// </summary>
         /// <param name="bundle">The bundle to retrieve the message from.</param>
         /// <param name="id">The identifier of the message.</param>
-        /// <param name="attribute">The attribute of the message (optional).</param>
-        /// <param name="args">The arguments for the message (optional).</param>
+        /// <param name="attribute">Optional attribute of the message.</param>
+        /// <param name="args">Optional arguments to be passed to the attribute message.</param>
         /// <param name="errors">When this method returns false, contains a list of errors that occurred while trying to retrieve the message; otherwise, null.</param>
         /// <param name="message">When this method returns true, contains the retrieved message; otherwise, null.</param>
         /// <returns>True if the message was successfully retrieved, otherwise false.</returns>
diff --git a/Linguini.Bundle/NonConcurrentBundle.cs b/Linguini.Bundle/NonConcurrentBundle.cs

Original file line number	Diff line number	Diff line change
`@@ -13,45 +13,33 @@`
`13`	`13`
`14`	`14`	`namespace Linguini.Bundle`
`15`	`15`	`{`
	`16`	`+ /// <summary>`
	`17`	`+ /// Represents a thread-safe implementation of the FluentBundle class.`
	`18`	`+ ///`
	`19`	+ /// `ConcurrentBundle` implements the <see cref="IReadBundle"/> interface.
	`20`	`+ /// </summary>`
`16`	`21`	`public sealed class ConcurrentBundle : FluentBundle, IEquatable<ConcurrentBundle>`
`17`	`22`	`{`
`18`	`23`	`internal ConcurrentDictionary<string, FluentFunction> Functions = new();`
`19`		`- private ConcurrentDictionary<string, AstTerm> _terms = new();`
`20`		`- private ConcurrentDictionary<string, AstMessage> _messages = new();`
`21`		`-`
`22`		`- public static ConcurrentBundle Thaw(FrozenBundle frozenBundle)`
`23`		`- {`
`24`		`- return new ConcurrentBundle`
`25`		`- {`
`26`		`- _messages = new ConcurrentDictionary<string, AstMessage>(frozenBundle.Messages),`
`27`		`- Functions = new ConcurrentDictionary<string, FluentFunction>(frozenBundle.Functions),`
`28`		`- _terms = new ConcurrentDictionary<string, AstTerm>(frozenBundle.Terms),`
`29`		`- FormatterFunc = frozenBundle.FormatterFunc,`
`30`		`- Locales = frozenBundle.Locales,`
`31`		`- UseIsolating = frozenBundle.UseIsolating,`
`32`		`- MaxPlaceable = frozenBundle.MaxPlaceable,`
`33`		`- EnableExtensions = frozenBundle.EnableExtensions,`
`34`		`- TransformFunc = frozenBundle.TransformFunc,`
`35`		`- Culture = frozenBundle.Culture`
`36`		`- };`
`37`		`- }`
	`24`	`+ internal ConcurrentDictionary<string, AstTerm> Terms = new();`
	`25`	`+ internal ConcurrentDictionary<string, AstMessage> Messages = new();`
`38`	`26`
`39`	`27`	`/// <inheritdoc />`
`40`	`28`	`protected override void AddMessageOverriding(AstMessage message)`
`41`	`29`	`{`
`42`		`- _messages[message.GetId()] = message;`
	`30`	`+ Messages[message.GetId()] = message;`
`43`	`31`	`}`
`44`	`32`
`45`	`33`	`/// <inheritdoc />`
`46`	`34`	`protected override void AddTermOverriding(AstTerm term)`
`47`	`35`	`{`
`48`		`- _terms[term.GetId()] = term;`
	`36`	`+ Terms[term.GetId()] = term;`
`49`	`37`	`}`
`50`	`38`
`51`	`39`	`/// <inheritdoc />`
`52`	`40`	`protected override bool TryAddTerm(AstTerm term, List<FluentError>? errors)`
`53`	`41`	`{`
`54`		`- if (_terms.TryAdd(term.GetId(), term)) return true;`
	`42`	`+ if (Terms.TryAdd(term.GetId(), term)) return true;`
`55`	`43`	`errors ??= new List<FluentError>();`
`56`	`44`	`errors.Add(new OverrideFluentError(term.GetId(), EntryKind.Term));`
`57`	`45`	`return false;`
`@@ -60,7 +48,7 @@ protected override bool TryAddTerm(AstTerm term, List<FluentError>? errors)`
`60`	`48`	`/// <inheritdoc />`
`61`	`49`	`protected override bool TryAddMessage(AstMessage message, List<FluentError>? errors)`
`62`	`50`	`{`
`63`		`- if (_messages.TryAdd(message.GetId(), message)) return true;`
	`51`	`+ if (Messages.TryAdd(message.GetId(), message)) return true;`
`64`	`52`	`errors ??= new List<FluentError>();`
`65`	`53`	`errors.Add(new OverrideFluentError(message.GetId(), EntryKind.Message));`
`66`	`54`	`return false;`
`@@ -89,19 +77,19 @@ public override void AddFunctionUnchecked(string funcName, ExternalFunction flue`
`89`	`77`	`/// <inheritdoc />`
`90`	`78`	`public override bool HasMessage(string identifier)`
`91`	`79`	`{`
`92`		`- return _messages.ContainsKey(identifier);`
	`80`	`+ return Messages.ContainsKey(identifier);`
`93`	`81`	`}`
`94`	`82`
`95`	`83`	`/// <inheritdoc />`
`96`	`84`	`public override bool TryGetAstMessage(string ident, [NotNullWhen(true)] out AstMessage? message)`
`97`	`85`	`{`
`98`		`- return _messages.TryGetValue(ident, out message);`
	`86`	`+ return Messages.TryGetValue(ident, out message);`
`99`	`87`	`}`
`100`	`88`
`101`	`89`	`/// <inheritdoc />`
`102`	`90`	`public override bool TryGetAstTerm(string ident, [NotNullWhen(true)] out AstTerm? term)`
`103`	`91`	`{`
`104`		`- return _terms.TryGetValue(ident, out term);`
	`92`	`+ return Terms.TryGetValue(ident, out term);`
`105`	`93`	`}`
`106`	`94`
`107`	`95`
`@@ -114,7 +102,7 @@ public override bool TryGetFunction(string funcName, [NotNullWhen(true)] out Flu`
`114`	`102`	`/// <inheritdoc />`
`115`	`103`	`public override IEnumerable<string> GetMessageEnumerable()`
`116`	`104`	`{`
`117`		`- return _messages.Keys;`
	`105`	`+ return Messages.Keys;`
`118`	`106`	`}`
`119`	`107`
`120`	`108`	`/// <inheritdoc />`
`@@ -126,19 +114,22 @@ public override IEnumerable<string> GetFuncEnumerable()`
`126`	`114`	`/// <inheritdoc />`
`127`	`115`	`public override IEnumerable<string> GetTermEnumerable()`
`128`	`116`	`{`
`129`		`- return _terms.Keys;`
	`117`	`+ return Terms.Keys;`
`130`	`118`	`}`
`131`	`119`
	`120`	`+ /// <inheritdoc/>`
`132`	`121`	`internal override IDictionary<string, AstMessage> GetMessagesDictionary()`
`133`	`122`	`{`
`134`		`- return _messages;`
	`123`	`+ return Messages;`
`135`	`124`	`}`
`136`	`125`
	`126`	`+ /// <inheritdoc/>`
`137`	`127`	`internal override IDictionary<string, AstTerm> GetTermsDictionary()`
`138`	`128`	`{`
`139`		`- return _terms;`
	`129`	`+ return Terms;`
`140`	`130`	`}`
`141`	`131`
	`132`	`+ /// <inheritdoc/>`
`142`	`133`	`internal override IDictionary<string, FluentFunction> GetFunctionDictionary()`
`143`	`134`	`{`
`144`	`135`	`return Functions;`
`@@ -150,8 +141,8 @@ public override FluentBundle DeepClone()`
`150`	`141`	`return new ConcurrentBundle`
`151`	`142`	`{`
`152`	`143`	`Functions = new ConcurrentDictionary<string, FluentFunction>(Functions),`
`153`		`- _terms = new ConcurrentDictionary<string, AstTerm>(_terms),`
`154`		`- _messages = new ConcurrentDictionary<string, AstMessage>(_messages),`
	`144`	`+ Terms = new ConcurrentDictionary<string, AstTerm>(Terms),`
	`145`	`+ Messages = new ConcurrentDictionary<string, AstMessage>(Messages),`
`155`	`146`	`Culture = (CultureInfo)Culture.Clone(),`
`156`	`147`	`Locales = new List<string>(Locales),`
`157`	`148`	`UseIsolating = UseIsolating,`
`@@ -167,8 +158,8 @@ public bool Equals(ConcurrentBundle? other)`
`167`	`158`	`{`
`168`	`159`	`if (ReferenceEquals(null, other)) return false;`
`169`	`160`	`if (ReferenceEquals(this, other)) return true;`
`170`		`- return base.Equals(other) && Functions.SequenceEqual(other.Functions) && _terms.SequenceEqual(other._terms) &&`
`171`		`- _messages.SequenceEqual(other._messages);`
	`161`	`+ return base.Equals(other) && Functions.SequenceEqual(other.Functions) && Terms.SequenceEqual(other.Terms) &&`
	`162`	`+ Messages.SequenceEqual(other.Messages);`
`172`	`163`	`}`
`173`	`164`
`174`	`165`	`/// <inheritdoc/>`
`@@ -180,7 +171,7 @@ public override bool Equals(object? obj)`
`180`	`171`	`/// <inheritdoc/>`
`181`	`172`	`public override int GetHashCode()`
`182`	`173`	`{`
`183`		`- return HashCode.Combine(base.GetHashCode(), Functions, _terms, _messages);`
	`174`	`+ return HashCode.Combine(base.GetHashCode(), Functions, Terms, Messages);`
`184`	`175`	`}`
`185`	`176`	`}`
`186`	`177`	`}`
Original file line number	Diff line number	Diff line change
`@@ -115,11 +115,13 @@ internal FrozenBundle(FluentBundle bundle)`
`115`	`115`	`Functions = new Dictionary<string, FluentFunction>(bundle.GetFunctionDictionary());`
`116`	`116`	`}`
`117`	`117`	`#endif`
	`118`	`+ /// <inheritdoc/>`
`118`	`119`	`public bool HasMessage(string identifier)`
`119`	`120`	`{`
`120`	`121`	`return Messages.ContainsKey(identifier);`
`121`	`122`	`}`
`122`	`123`
	`124`	`+ /// <inheritdoc/>`
`123`	`125`	`public string FormatPattern(Pattern pattern, IDictionary<string, IFluentType>? args,`
`124`	`126`	`[NotNullWhen(false)] out IList<FluentError>? errors)`
`125`	`127`	`{`
`@@ -129,36 +131,43 @@ public string FormatPattern(Pattern pattern, IDictionary<string, IFluentType>? a`
`129`	`131`	`return value.AsString();`
`130`	`132`	`}`
`131`	`133`
	`134`	`+ /// <inheritdoc/>`
`132`	`135`	`public bool TryGetAstMessage(string ident, [NotNullWhen(true)] out AstMessage? message)`
`133`	`136`	`{`
`134`	`137`	`return Messages.TryGetValue(ident, out message);`
`135`	`138`	`}`
`136`	`139`
	`140`	`+ /// <inheritdoc/>`
`137`	`141`	`public bool TryGetAstTerm(string ident, [NotNullWhen(true)] out AstTerm? term)`
`138`	`142`	`{`
`139`	`143`	`return Terms.TryGetValue(ident, out term);`
`140`	`144`	`}`
`141`	`145`
	`146`	`+ /// <inheritdoc/>`
`142`	`147`	`public bool TryGetFunction(Identifier id, [NotNullWhen(true)] out FluentFunction? function)`
`143`	`148`	`{`
`144`	`149`	`return Functions.TryGetValue(id.ToString(), out function);`
`145`	`150`	`}`
`146`	`151`
	`152`	`+ /// <inheritdoc/>`
`147`	`153`	`public bool TryGetFunction(string funcName, [NotNullWhen(true)] out FluentFunction? function)`
`148`	`154`	`{`
`149`	`155`	`return Functions.TryGetValue(funcName, out function);`
`150`	`156`	`}`
`151`	`157`
	`158`	`+ /// <inheritdoc/>`
`152`	`159`	`public IEnumerable<string> GetMessageEnumerable()`
`153`	`160`	`{`
`154`	`161`	`return Messages.Keys;`
`155`	`162`	`}`
`156`	`163`
	`164`	`+ /// <inheritdoc/>`
`157`	`165`	`public IEnumerable<string> GetFuncEnumerable()`
`158`	`166`	`{`
`159`	`167`	`return Functions.Keys;`
`160`	`168`	`}`
`161`	`169`
	`170`	`+ /// <inheritdoc/>`
`162`	`171`	`public IEnumerable<string> GetTermEnumerable()`
`163`	`172`	`{`
`164`	`173`	`return Terms.Keys;`