From 66041a35228a06d7737ebd7419d8e7afd012f761 Mon Sep 17 00:00:00 2001 From: ahall Date: Sat, 11 Jul 2026 09:18:25 +0100 Subject: [PATCH] docs: resolve CS1574 unresolved crefs and CS1571 duplicate param in TodoApp.BlazorWasm.Client TodoService Fixes unresolved XML doc tags and a duplicate tag surfaced when building TodoApp.BlazorWasm.Client with -p:GenerateDocumentationFile=true: - ValidationException and ConcurrencyException don't exist in CommunityToolkit.Datasync.Client; the client actually throws ConflictException on version/duplicate conflicts and EntityDoesNotExistException when an item is missing. Exception docs on CreateTodoItemAsync/UpdateTodoItemAsync/DeleteTodoItemAsync are updated to reference these real types. - AddAsync(T)/ReplaceAsync(T) crefs pointed at nonexistent overloads on DatasyncServiceClient; the code actually calls the IDatasyncServiceClientExtensions.AddAsync/ReplaceAsync extension methods, so the crefs now target those. - RemoveAsync(string, DatasyncServiceOptions) was missing its CancellationToken parameter in the cref. - Merged the duplicate tag on CreateTodoItemAsync in both files into a single tag. Fixes #550 --- .../Services/ITodoService.cs | 28 +++++++------ .../Services/TodoService.cs | 42 +++++++++++-------- 2 files changed, 40 insertions(+), 30 deletions(-) diff --git a/samples/todoapp-blazor-wasm/TodoApp.BlazorWasm.Client/Services/ITodoService.cs b/samples/todoapp-blazor-wasm/TodoApp.BlazorWasm.Client/Services/ITodoService.cs index c382a397..93b2ca68 100644 --- a/samples/todoapp-blazor-wasm/TodoApp.BlazorWasm.Client/Services/ITodoService.cs +++ b/samples/todoapp-blazor-wasm/TodoApp.BlazorWasm.Client/Services/ITodoService.cs @@ -2,6 +2,7 @@ // The .NET Foundation licenses this file to you under the MIT license. // See the LICENSE file in the project root for more information. +using CommunityToolkit.Datasync.Client; using TodoApp.BlazorWasm.Shared.Models; namespace TodoApp.BlazorWasm.Client.Services; @@ -74,7 +75,10 @@ public interface ITodoService /// /// Creates a new todo item with the specified title. /// - /// The title or description of the new todo item. + /// + /// The title for the new todo item. Should not be null, empty, or consist only of whitespace. + /// The title length should comply with validation rules defined in . + /// /// /// A that represents the asynchronous operation. /// The task result contains the newly created with @@ -92,10 +96,6 @@ public interface ITodoService /// concurrency control, and any other metadata required by the datasync framework. /// /// - /// - /// The title for the new todo item. Should not be null, empty, or consist only of whitespace. - /// The title length should comply with validation rules defined in . - /// /// /// Thrown when is null. /// @@ -107,8 +107,8 @@ public interface ITodoService /// Thrown when the service fails to create the todo item due to server errors, /// network issues, or other operational problems. /// - /// - /// Thrown when the todo item data fails validation on the server side. + /// + /// Thrown when a todo item with the same identifier already exists in the remote service dataset. /// Task CreateTodoItemAsync(string title); @@ -143,15 +143,15 @@ public interface ITodoService /// /// /// Thrown when the update operation fails due to server errors, network issues, - /// concurrent modifications, or when the item no longer exists on the server. - /// - /// - /// Thrown when the updated todo item data fails server-side validation. + /// or other operational problems. /// - /// + /// /// Thrown when the item has been modified by another client and the update /// cannot be completed due to version conflicts. /// + /// + /// Thrown when the item no longer exists on the server. + /// Task UpdateTodoItemAsync(TodoItemDto item); /// @@ -193,5 +193,9 @@ public interface ITodoService /// /// Thrown when the current user is not authorized to delete the specified todo item. /// + /// + /// Thrown by implementations (such as ) that surface a missing + /// or already-deleted item as an error rather than treating it as a successful no-op. + /// Task DeleteTodoItemAsync(string id); } diff --git a/samples/todoapp-blazor-wasm/TodoApp.BlazorWasm.Client/Services/TodoService.cs b/samples/todoapp-blazor-wasm/TodoApp.BlazorWasm.Client/Services/TodoService.cs index e8532c8e..acb9ab13 100644 --- a/samples/todoapp-blazor-wasm/TodoApp.BlazorWasm.Client/Services/TodoService.cs +++ b/samples/todoapp-blazor-wasm/TodoApp.BlazorWasm.Client/Services/TodoService.cs @@ -76,7 +76,7 @@ public async Task> GetTodoItemsAsync() /// /// Creates a new todo item with the specified title. /// - /// The title or description of the new todo item. + /// The title for the new todo item. Must not be null or empty. /// /// A that represents the asynchronous operation. /// The task result contains the newly created with @@ -90,11 +90,11 @@ public async Task> GetTodoItemsAsync() /// /// /// The method sends the new item to the server via the datasync client's - /// method. Upon successful creation, - /// the server returns the persisted item with updated timestamps and version information. + /// + /// method. Upon successful creation, the server returns the persisted item with updated + /// timestamps and version information. /// /// - /// The title for the new todo item. Must not be null or empty. /// /// Thrown when is null. /// @@ -104,8 +104,8 @@ public async Task> GetTodoItemsAsync() /// /// Thrown when the server operation fails, containing details about the failure reason. /// - /// - /// Thrown when the todo item fails server-side validation (e.g., title too long). + /// + /// Thrown when a todo item with the same identifier already exists in the remote service dataset. /// public async Task CreateTodoItemAsync(string title) { @@ -131,24 +131,28 @@ public async Task CreateTodoItemAsync(string title) /// /// /// This method performs a complete replacement of the todo item on the server using - /// the datasync client's method. - /// The operation includes optimistic concurrency control based on the item's version property. + /// the datasync client's + /// method. The operation includes optimistic concurrency control based on the item's version property. /// /// /// If the item has been modified by another client since it was last retrieved, - /// the server will reject the update with a conflict status, which will be reflected - /// in the returned by the datasync client. + /// the server will reject the update with a conflict status, which is surfaced as a + /// by the datasync client. /// /// /// /// Thrown when is null. /// /// - /// Thrown when the server operation fails, including conflicts due to concurrent modifications, - /// validation failures, or network errors. The exception message includes the server's reason phrase. + /// Thrown when the server operation fails due to network errors or other operational + /// problems. The exception message includes the server's reason phrase. /// - /// - /// Thrown when the updated todo item fails server-side validation. + /// + /// Thrown when the item has been modified by another client since it was last retrieved, + /// causing a version conflict. + /// + /// + /// Thrown when the item no longer exists on the server. /// public async Task UpdateTodoItemAsync(TodoItemDto item) { @@ -177,7 +181,7 @@ public async Task UpdateTodoItemAsync(TodoItemDto item) /// /// /// The method uses to configure the delete operation - /// and leverages the datasync client's + /// and leverages the datasync client's /// method to perform the server-side operation. /// /// @@ -192,9 +196,11 @@ public async Task UpdateTodoItemAsync(TodoItemDto item) /// Thrown when is empty or whitespace only. /// /// - /// Thrown when the server operation fails, such as when the item doesn't exist, - /// has already been deleted, or due to network connectivity issues. - /// The exception message includes the server's reason phrase. + /// Thrown when the server operation fails due to network connectivity issues or + /// other operational problems. The exception message includes the server's reason phrase. + /// + /// + /// Thrown when the item doesn't exist or has already been deleted on the server. /// public async Task DeleteTodoItemAsync(string id) {