Merge pull request #1520 from unoplatform/dev/nr/issue1516_2

chore: Adding docs for storage

src/Uno.Extensions.Configuration/AppConfiguration.cs

@@ -1,6 +1,6 @@
 namespace Uno.Extensions.Configuration;
 
-public class AppConfiguration
+internal static class AppConfiguration
 {
 	public const string Prefix = "appsettings";
 	public const string FileName = $"{Prefix}.json";

src/Uno.Extensions.Storage.UI/GlobalUsings.cs

@@ -2,13 +2,15 @@
 global using System.Collections.Generic;
 global using System.IO;
 global using System.Linq;
+global using System.Reflection;
 global using System.Threading;
 global using System.Threading.Tasks;
 global using Microsoft.Extensions.DependencyInjection;
 global using Microsoft.Extensions.Hosting;
 global using Microsoft.Extensions.Logging;
 global using Microsoft.Extensions.Options;
 global using Uno.Extensions.Configuration;
+global using Uno.Extensions.DependencyInjection;
 global using Uno.Extensions.Logging;
 global using Uno.Extensions.Serialization;
 global using Uno.Extensions.Storage;
@@ -18,7 +20,7 @@
 global using Windows.Storage;
 
 #if WINUI
-global using Microsoft.UI.Dispatching;
+	global using Microsoft.UI.Dispatching;
 	global using Microsoft.UI.Xaml;
 	global using Microsoft.UI.Xaml.Controls;
 	global using Microsoft.UI.Xaml.Controls.Primitives;

src/Uno.Extensions.Storage.UI/HostBuilderExtensions.cs

@@ -1,23 +1,32 @@
-
-
-using Uno.Extensions.Configuration;
-
-namespace Uno.Extensions;
+namespace Uno.Extensions;
 
+/// <summary>
+/// Extensions for working with <see cref="IHostBuilder"/>.
+/// </summary>
 public static class HostBuilderExtensions
 {
+	/// <summary>
+	/// Registers storage services.
+	/// </summary>
+	/// <param name="hostBuilder">The host builder instance to register with</param>
+	/// <param name="configure">Callback for configuring services</param>
+	/// <returns>The updated host builder instance</returns>
 	public static IHostBuilder UseStorage(
 		this IHostBuilder hostBuilder,
 		Action<IServiceCollection> configure)
-	{
-		return hostBuilder.UseStorage((context, builder) => configure.Invoke(builder));
-	}
+			=> hostBuilder.UseStorage((context, builder) => configure.Invoke(builder));
 
+	/// <summary>
+	/// Registers storage services
+	/// </summary>
+	/// <param name="hostBuilder">The host builder instance to register with</param>
+	/// <param name="configure">Callback for configuring services</param>
+	/// <returns></returns>
 	public static IHostBuilder UseStorage(
-		this IHostBuilder builder,
+		this IHostBuilder hostBuilder,
 		Action<HostBuilderContext, IServiceCollection>? configure = default)
 	{
-		return builder
+		return hostBuilder
 			.UseConfiguration(
 				configure: configBuilder =>
 				{

src/Uno.Extensions.Storage.UI/ServiceCollectionExtensions.cs

@@ -1,17 +1,10 @@
-using System.Reflection;
-using Microsoft.Extensions.DependencyInjection.Extensions;
-using Uno.Extensions.DependencyInjection;
+namespace Uno.Extensions;
 
-namespace Uno.Extensions;
-
-public static class ServiceCollectionExtensions
+internal static class ServiceCollectionExtensions
 {
-
 	public static IServiceCollection AddFileStorage(this IServiceCollection services)
-	{
-		return services
+		=> services
 			.AddSingleton<IStorage, FileStorage>();
-	}
 
 	private static TKeyValueStorage CreateKeyValueStorage<TKeyValueStorage>(
 		this IServiceProvider sp,

src/Uno.Extensions.Storage/IDataFolderProvider.cs

@@ -1,6 +1,12 @@
 namespace Uno.Extensions.Storage;
 
+/// <summary>
+/// Interface for providing the data folder path for the application
+/// </summary>
 public interface IDataFolderProvider
 {
+	/// <summary>
+	/// The path to the application data folder
+	/// </summary>
 	string? AppDataPath { get; }
 }

src/Uno.Extensions.Storage/KeyValueStorage/KeyValueStorageConfiguration.cs

@@ -1,28 +1,6 @@
 namespace Uno.Extensions.Storage.KeyValueStorage;
 
-public record KeyValueStorageConfiguration : KeyValueStorageSettings
+internal record KeyValueStorageConfiguration : KeyValueStorageSettings
 {
 	public IDictionary<string, KeyValueStorageSettings> Providers { get; init; } = new Dictionary<string, KeyValueStorageSettings>();
-
-
-}
-
-internal static class KeyValueStorageConfigurationExtensions
-{
-	public static KeyValueStorageSettings GetSettingsOrDefault(this KeyValueStorageConfiguration? config, string name)
-	{
-		if (config?.Providers.TryGetValue(name, out var settings) ?? false)
-		{
-			return settings;
-		}
-
-		// If there isn't a match for settings for the supplied name, return
-		// the default settings
-		return config ?? new KeyValueStorageSettings();
-	}
-}
-
-public record KeyValueStorageSettings
-{
-	public bool DisableInMemoryCache { get; init; }
 }

src/Uno.Extensions.Storage/KeyValueStorage/KeyValueStorageConfigurationExtensions.cs

@@ -0,0 +1,16 @@
+namespace Uno.Extensions.Storage.KeyValueStorage;
+
+internal static class KeyValueStorageConfigurationExtensions
+{
+	public static KeyValueStorageSettings GetSettingsOrDefault(this KeyValueStorageConfiguration? config, string name)
+	{
+		if (config?.Providers.TryGetValue(name, out var settings) ?? false)
+		{
+			return settings;
+		}
+
+		// If there isn't a match for settings for the supplied name, return
+		// the default settings
+		return config ?? new KeyValueStorageSettings();
+	}
+}

src/Uno.Extensions.Storage/KeyValueStorage/KeyValueStorageExtensions.cs

@@ -1,13 +1,30 @@
 namespace Uno.Extensions.Storage.KeyValueStorage;
 
+/// <summary>
+/// Extensions for working with <see cref="IKeyValueStorage"/>.
+/// </summary>
 public static class KeyValueStorageExtensions
 {
+	/// <summary>
+	/// Determines if the storage contains the specified key.
+	/// </summary>
+	/// <param name="storage">The storage instance</param>
+	/// <param name="key">The key to search for</param>
+	/// <param name="ct">CancellationToken to cancel operation</param>
+	/// <returns>True if storage contains key</returns>
 	public static async ValueTask<bool> ContainsKey(this IKeyValueStorage storage, string key, CancellationToken ct)
 	{
 		var keys = await storage.GetKeysAsync(ct);
 		return keys.Contains(key);
 	}
 
+	/// <summary>
+	/// Gets a value from the storage as a string
+	/// </summary>
+	/// <param name="storage">The storage instance</param>
+	/// <param name="key">The key to retrieve</param>
+	/// <param name="ct">CancellationToken to cancel operation</param>
+	/// <returns>The value, or null if key not in storage</returns>
 	public static async ValueTask<string?> GetStringAsync(
 		this IKeyValueStorage storage,
 		string key,
@@ -21,16 +38,28 @@ public static async ValueTask<bool> ContainsKey(this IKeyValueStorage storage, s
 		return default;
 	}
 
+	/// <summary>
+	/// Retrieves all key/value pairs from the storage.
+	/// </summary>
+	/// <param name="storage">The storage instance</param>
+	/// <param name="ct">CancellationToken to cancel operation</param>
+	/// <returns>Dictionary of key-value pairs</returns>
 	public static ValueTask<IDictionary<string, string>> GetAllValuesAsync(
 		this IKeyValueStorage storage,
 		CancellationToken ct)
-	{
-		return GetAllValuesAsync(storage, _ => true, ct);
-	}
+			=> GetAllValuesAsync(storage, _ => true, ct);
+
+	/// <summary>
+	/// Retrieves all key/value pairs from the storage that match the predicate.
+	/// </summary>
+	/// <param name="storage">The storage instance</param>
+	/// <param name="predicate">The predicate to invoke to determine if pair should be returned</param>
+	/// <param name="ct">CancellationToken to cancel operation</param>
+	/// <returns>Dictionary of key-value pairs</returns>
 	public static async ValueTask<IDictionary<string, string>> GetAllValuesAsync(
-	this IKeyValueStorage storage,
-	Func<string, bool> predicate,
-	CancellationToken ct)
+		this IKeyValueStorage storage,
+		Func<string, bool> predicate,
+		CancellationToken ct)
 	{
 		var dict = new Dictionary<string, string>();
 		var keys = await storage.GetKeysAsync(ct);
@@ -45,13 +74,24 @@ public static async ValueTask<IDictionary<string, string>> GetAllValuesAsync(
 		return dict;
 	}
 
+	/// <summary>
+	/// Clear all values from the storage.
+	/// </summary>
+	/// <param name="storage">The storage instance</param>
+	/// <param name="ct">CancellationToken to cancel operation</param>
+	/// <returns>Task to await</returns>
 	public static ValueTask ClearAllAsync(
 	this IKeyValueStorage storage,
 	CancellationToken ct)
-	{
-		return ClearAllAsync(storage, _ => true, ct);	
-	}
+		=> ClearAllAsync(storage, _ => true, ct);
 
+	/// <summary>
+	/// Clear all values from storage that match the predicate.
+	/// </summary>
+	/// <param name="storage">The storage instance</param>
+	/// <param name="predicate">The predicate to invoke to determine if pair should be cleared</param>
+	/// <param name="ct">CancellationToken to cancel operation</param>
+	/// <returns>Task to await</returns>
 	public static async ValueTask ClearAllAsync(
 		this IKeyValueStorage storage,
 		Func<string, bool> predicate,

src/Uno.Extensions.Storage/KeyValueStorage/KeyValueStorageSettings.cs

@@ -0,0 +1,12 @@
+namespace Uno.Extensions.Storage.KeyValueStorage;
+
+/// <summary>
+/// Record for storing settings for a key value storage provider.
+/// </summary>
+public record KeyValueStorageSettings
+{
+	/// <summary>
+	/// Gets or sets whether in-memory cache should be disabled.
+	/// </summary>
+	public bool DisableInMemoryCache { get; init; }
+}

src/Uno.Extensions.Storage/StorageExtensions.cs

@@ -1,11 +1,22 @@
 namespace Uno.Extensions.Storage;
 
+/// <summary>
+/// Extensions for working with <see cref="IStorage"/>.
+/// </summary>
 public static class StorageExtensions
 {
+	/// <summary>
+	/// Reads the contents of a file and deserializes to the specified type
+	/// </summary>
+	/// <typeparam name="TData">The type to deserialize to</typeparam>
+	/// <param name="storage">The storage instance</param>
+	/// <param name="serializer">The serializer to use</param>
+	/// <param name="fileName">The relative path of the file to read from</param>
+	/// <returns>The instance read, or null if file isn't found </returns>
 	public static async Task<TData?> ReadPackageFileAsync<TData>(this IStorage storage, ISerializer serializer, string fileName)
 	{
 		using var stream = await storage.OpenPackageFileAsync(fileName);
-		if(stream is null)
+		if (stream is null)
 		{
 			return default;
 		}