Adding some comments to the code.

Author: timunie

src/Avalonia.Samples/CompleteApps/AdvancedToDoList/AdvancedToDoList/Assets/Icons.axaml

@@ -6,10 +6,17 @@
 
 namespace AdvancedToDoList.DataTemplates;
 
+/// <summary>
+/// This class is a helper to resolve the symbol-representation of our <see cref="Priority"/>-enum
+/// </summary>
 public class ToDoItemPriorityIconTemplateSelector : IDataTemplate
 {
+    /// <summary>
+    /// Gets the default instance of this class
+    /// </summary>
     public static ToDoItemPriorityIconTemplateSelector Instance { get; } = new ToDoItemPriorityIconTemplateSelector();
 
+    /// <inheritdoc />
     public Control? Build(object? param)
     {
         var priority = param as Priority?;
@@ -38,15 +45,16 @@ public class ToDoItemPriorityIconTemplateSelector : IDataTemplate
                 new PathIcon()
                 {
                     Data = ResourcesHelper.GetAppResource<Geometry>("PhosphorIcons.ArrowCircleUpRight"),
-                    Foreground = new SolidColorBrush(Colors.Red),
+                    Foreground = Brushes.Red,
                     Width = fontSize, 
                     Height = fontSize
                 },
 
             _ => null
         };
-    }    
-    
+    }
+
+    /// <inheritdoc />
     public bool Match(object? data)
     {
         return data is Priority;

src/Avalonia.Samples/CompleteApps/AdvancedToDoList/AdvancedToDoList/DataTemplates/ToDoItemPriorityIconTemplateSelector.cs

@@ -6,10 +6,17 @@
 
 namespace AdvancedToDoList.DataTemplates;
 
+/// <summary>
+/// This class is a helper to resolve the symbol for the <see cref="ToDoItemStatus"/>.
+/// </summary>
 public class ToDoItemStatusTemplateSelector : IDataTemplate
 {
+    /// <summary>
+    /// Gets the default instance of this class
+    /// </summary>
     public static ToDoItemStatusTemplateSelector Instance { get; } = new ToDoItemStatusTemplateSelector();
-    
+
+    /// <inheritdoc />
     public Control? Build(object? param)
     {
         var status = param as ToDoItemStatus?;
@@ -20,7 +27,9 @@ public class ToDoItemStatusTemplateSelector : IDataTemplate
                 {
                     Data = ResourcesHelper.GetAppResource<Geometry>("PhosphorIcons.CircleDashedLight"),
                     Opacity = 0.7,
-                    [ToolTip.TipProperty] = "Pending"
+                    // TIP: If you want your App to be localized, you could also provide this text via App.Resources
+                    // or any other localization provider.
+                    [ToolTip.TipProperty] = "Pending" 
                 },
 
             ToDoItemStatus.InProgress => 
@@ -50,7 +59,8 @@ public class ToDoItemStatusTemplateSelector : IDataTemplate
             _ => null
         };
     }
-    
+
+    /// <inheritdoc />
     public bool Match(object? data)
     {
         return data is ToDoItemStatus;

src/Avalonia.Samples/CompleteApps/AdvancedToDoList/AdvancedToDoList/DataTemplates/TodoItemStatusTemplateSelector.cs

@@ -3,9 +3,16 @@
 
 namespace AdvancedToDoList.Helper;
 
-public class ColorHelper
+/// <summary>
+/// An internal helper class for the <see cref="Avalonia.Media.Color"/>-struct
+/// </summary>
+internal static class ColorHelper
 {
-    public static Color GetRandomColor()
+    /// <summary>
+    /// Creates a Random Color using RGB
+    /// </summary>
+    /// <returns>The random Color</returns>
+    internal static Color GetRandomColor()
     {
         return new Color(
             255,

src/Avalonia.Samples/CompleteApps/AdvancedToDoList/AdvancedToDoList/Helper/ColorHelper.cs

@@ -2,9 +2,19 @@
 
 namespace AdvancedToDoList.Helper;
 
+/// <summary>
+/// This is Data-Transfer-Object used to convert the DataBase from and to JSON-representation.
+/// </summary>
+/// <seealso href="https://en.wikipedia.org/wiki/Data_transfer_object"/>
 public class DataBaseDto
 {
+    /// <summary>
+    /// Gets or sets a collection of available Categories.
+    /// </summary>
     public Category[]? Categories { get; set; }
 
+    /// <summary>
+    /// Gets or sets a collection of available ToDoItems.
+    /// </summary>
     public ToDoItem[]? ToDoItems { get; set; }
 }

src/Avalonia.Samples/CompleteApps/AdvancedToDoList/AdvancedToDoList/Helper/DataBaseDto.cs

@@ -12,28 +12,37 @@
 using Microsoft.Data.Sqlite;
 using Microsoft.Extensions.DependencyInjection;
 
+// Needed to make Dapper AOT-friendly.
+// See: https://aot.dapperlib.dev for usage details
 [module: DapperAot]
 
 namespace AdvancedToDoList.Helper;
 
+/// <summary>
+/// This is a helper class for working with our DataBase.
+/// </summary>
 public static class DataBaseHelper
 {
+    // A flag that indicates if the DB is yet initialized.
     private static bool _initialized;
 
+    /// <summary>
+    /// Opens a new <see cref="SqliteConnection"/> and opens it for usage. 
+    /// </summary>
+    /// <remarks>
+    /// Ensure the connection is disposed of after use.
+    /// </remarks>
+    /// <returns>The open connection.</returns>
     internal static async Task<SqliteConnection> GetOpenConnectionAsync()
     {
-        if (Design.IsDesignMode)
-        {
-            Console.WriteLine(App.Services.GetService<IDbService>() is not null ? "Service found" : "Service not found");
-        }
-
+        // Get the DB-service to resolve the DB per platfrom correctly.
         var dbService = App.Services.GetRequiredService<IDbService>();
-
+        
         var dbPath = dbService.GetDatabasePath();
         var dbSource = $"Data Source='{dbPath}'";
 
         // Ensure the directory exists for the database file
-        string? dir = Path.GetDirectoryName(dbPath);
+        var dir = Path.GetDirectoryName(dbPath);
         if (!string.IsNullOrEmpty(dir) && !Directory.Exists(dir))
         {
             Directory.CreateDirectory(dir);
@@ -42,34 +51,50 @@ internal static async Task<SqliteConnection> GetOpenConnectionAsync()
         var connection = new SqliteConnection(dbSource);
         await connection.OpenAsync();
 
+        // make sure the necessary DB-schema is created.
         await EnsureInitializedAsync(connection);
-        Console.WriteLine($"Opened database at {dbPath}");
 
         return connection;
     }
 
-    
+    /// <summary>
+    /// Gets all available Categories from the DB.
+    /// </summary>
+    /// <returns>the loaded Categories</returns>
     public static async Task<IEnumerable<Category>> GetCategoriesAsync()
     {
         await using var connection = await GetOpenConnectionAsync();
         return (await connection.QueryAsync<Category>("SELECT * FROM Category"));
     }
 
+    /// <summary>
+    /// Gets all available ToDoItems from the DB, filtered by its status.
+    /// </summary>
+    /// <param name="loadAlsoCompletedItems">If true, also loads items that are marked as compleded (Progess = 100 %). The default is false.</param>
+    /// <returns>the loaded ToDoItems</returns>
     public static async Task<IEnumerable<ToDoItem>> GetToDoItemsAsync(bool loadAlsoCompletedItems = false)
     {
-        Console.WriteLine("GetToDoItemsAsync");
         await using var connection = await GetOpenConnectionAsync();
+        // The trick here is to pass @loadAlsoCompletedItems as a parameter.
+        // If it is true, the condition will always be true. 
+        // The alternative would be to write different SQL queries.
         const string sql = """
                            SELECT *
                            FROM ToDoItem 
-                           WHERE Progress < 100 OR @loadAlsoCompletedItems;
+                           WHERE @loadAlsoCompletedItems OR Progress < 100;
                            """;
 
+        // store the items into an array
         var toDoItems = 
             (await connection.QueryAsync<ToDoItem>(sql,
             new {loadAlsoCompletedItems}))
             .ToArray();
 
+        // map the categories.
+        // Dapper could also to it directly in the query.
+        // However, this would need reflection and NativeAOT would not work properly. 
+        // Thus, we will map the categories to CategoryId on our own. 
+        
         var categories = await connection.QueryAsync<Category>("SELECT * FROM Category");
         var categoriesDict = new Dictionary<long, Category>(
             categories.Select(x => new KeyValuePair<long, Category>(x.Id ?? -1, x)));
@@ -86,7 +111,7 @@ FROM ToDoItem
     /// Ensures that all tables are created and the database is ready to be used.
     /// </summary>
     /// <param name="connection">the connection to use</param>
-    /// <param name="force">the creating will be skipped by default, unless you set this parameter to true</param>
+    /// <param name="force">the creating will be skipped by default, unless you set this parameter to true.</param>
     internal static async Task EnsureInitializedAsync(SqliteConnection connection, bool force = false)
     {
         if (_initialized && !force) return;
@@ -121,6 +146,7 @@ Color TEXT NULL
 
         Console.WriteLine("Created Category table.");
 
+        // Populate some data for the designer if it has none yet. 
         if (Design.IsDesignMode)
         {
             var categoryCount = await connection.ExecuteScalarAsync<int>("SELECT COUNT(*) FROM Category");
@@ -142,13 +168,17 @@ Color TEXT NULL
     /// </summary>
     /// <remarks>
     /// Wasm uses IndexedDB to store the data. This needs to be synced.
-    /// This helper will do it for us.
+    /// This helper will do it for us. If you don't need the WASM-target, this can be omitted. 
     /// </remarks>
     public static async Task SyncUnderlyingDatabaseAsync()
     {
         await App.Services.GetRequiredService<IDbService>().SaveAsync();
     }
 
+    /// <summary>
+    /// Adds some sample data for the designer.
+    /// </summary>
+    /// <param name="connection">The connection to use.</param>
     private static async Task AddSampleDataAsync(SqliteConnection connection)
     {
 

src/Avalonia.Samples/CompleteApps/AdvancedToDoList/AdvancedToDoList/Helper/DataBaseHelper.cs

@@ -2,9 +2,17 @@
 
 namespace AdvancedToDoList.Helper;
 
-public static class FileHelper
+/// <summary>
+/// An internal helper for working with File-I/O.
+/// </summary>
+internal static class FileHelper
 {
-    public static FilePickerFileType JsonFileType { get; } = new FilePickerFileType("Json file")
+    /// <summary>
+    /// Gets the <see cref="FilePickerFileType"/> that represents a JSON file. 
+    /// </summary>
+    /// <seealso href="https://developer.apple.com/documentation/uniformtypeidentifiers"/>
+    /// <seealso href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types/Common_types"/>
+    internal static FilePickerFileType JsonFileType { get; } = new FilePickerFileType("Json file")
     {
         Patterns = ["*.json"],
         AppleUniformTypeIdentifiers = ["public.json"],

src/Avalonia.Samples/CompleteApps/AdvancedToDoList/AdvancedToDoList/Helper/FileHelper.cs

@@ -7,6 +7,11 @@
 
 namespace AdvancedToDoList.Helper;
 
+/// <summary>
+/// This class is the <see cref="JsonSerializerContext"/> which is needed to make the serialization
+/// AOT and trimming friendly.
+/// </summary>
+/// <see href="https://learn.microsoft.com/en-us/dotnet/standard/serialization/system-text-json/source-generation"/>
 [JsonSerializable(typeof(DataBaseDto))]
 [JsonSerializable(typeof(Settings))]
 [JsonSerializable(typeof(Category[]))]
@@ -21,6 +26,9 @@ public partial class JsonContextHelper : JsonSerializerContext
 {
 }
 
+/// <summary>
+/// This class converts a <see cref="Color"/> from and to JSON.
+/// </summary>
 public class JsonColorConverter : JsonConverter<Color>
 {
     public override Color Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)

src/Avalonia.Samples/CompleteApps/AdvancedToDoList/AdvancedToDoList/Helper/JsonContextHelper.cs

@@ -4,8 +4,17 @@
 
 namespace AdvancedToDoList.Helper;
 
+/// <summary>
+/// This is an interal helper class to work with App-resources.
+/// </summary>
 internal static class ResourcesHelper
 {
+    /// <summary>
+    /// This method will look up all App-resources and return the found value or the default if nothing was found.
+    /// </summary>
+    /// <param name="resourceKey">The resource key to lookup.</param>
+    /// <typeparam name="T">The expected return type.</typeparam>
+    /// <returns>the found value if present, otherwise its default value.</returns>
     internal static T? GetAppResource<T>(object resourceKey)
     {
         var found = Application.Current!.TryFindResource(resourceKey, out var resource);

src/Avalonia.Samples/CompleteApps/AdvancedToDoList/AdvancedToDoList/Helper/ResourcesHelper.cs

@@ -1,8 +1,18 @@
-using System;
+using CommunityToolkit.Mvvm.Messaging;
 
 namespace AdvancedToDoList.Messages;
 
+/// <summary>
+/// A class that repsents a message for communication between different ViewModels.
+/// It notifies about changed objects that should update.
+/// </summary>
+/// <param name="affectedItems">the updated items</param>
+/// <typeparam name="T">the type of the updated items</typeparam>
+/// <remarks>Used via <see cref="WeakReferenceMessenger"/>.</remarks>
 public class UpdateDataRequest<T>(params T[] affectedItems)
 {
+    /// <summary>
+    /// Gets the items that were updated.
+    /// </summary>
     public T[] ItemsAffected => affectedItems;
 }