docs: resolve CS1574 unresolved crefs and CS1571 duplicate param in TodoApp.BlazorWasm.Client TodoService

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
     /// <summary>
     /// Creates a new todo item with the specified title.
     /// </summary>
-    /// <param name="title">The title or description of the new todo item.</param>
+    /// <param name="title">
+    /// 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 <see cref="TodoItemDto"/>.
+    /// </param>
     /// <returns>
     /// A <see cref="Task{TResult}"/> that represents the asynchronous operation.
     /// The task result contains the newly created <see cref="TodoItemDto"/> with
@@ -92,10 +96,6 @@ public interface ITodoService
     /// concurrency control, and any other metadata required by the datasync framework.
     /// </para>
     /// </remarks>
-    /// <param name="title">
-    /// 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 <see cref="TodoItemDto"/>.
-    /// </param>
     /// <exception cref="ArgumentNullException">
     /// Thrown when <paramref name="title"/> is <c>null</c>.
     /// </exception>
@@ -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.
     /// </exception>
-    /// <exception cref="ValidationException">
-    /// Thrown when the todo item data fails validation on the server side.
+    /// <exception cref="ConflictException{TodoItemDto}">
+    /// Thrown when a todo item with the same identifier already exists in the remote service dataset.
     /// </exception>
     Task<TodoItemDto> CreateTodoItemAsync(string title);
 
@@ -143,15 +143,15 @@ public interface ITodoService
     /// </exception>
     /// <exception cref="InvalidOperationException">
     /// Thrown when the update operation fails due to server errors, network issues,
-    /// concurrent modifications, or when the item no longer exists on the server.
-    /// </exception>
-    /// <exception cref="ValidationException">
-    /// Thrown when the updated todo item data fails server-side validation.
+    /// or other operational problems.
     /// </exception>
-    /// <exception cref="ConcurrencyException">
+    /// <exception cref="ConflictException{TodoItemDto}">
     /// Thrown when the item has been modified by another client and the update
     /// cannot be completed due to version conflicts.
     /// </exception>
+    /// <exception cref="EntityDoesNotExistException">
+    /// Thrown when the item no longer exists on the server.
+    /// </exception>
     Task<TodoItemDto> UpdateTodoItemAsync(TodoItemDto item);
 
     /// <summary>
@@ -193,5 +193,9 @@ public interface ITodoService
     /// <exception cref="UnauthorizedAccessException">
     /// Thrown when the current user is not authorized to delete the specified todo item.
     /// </exception>
+    /// <exception cref="EntityDoesNotExistException">
+    /// Thrown by implementations (such as <see cref="TodoService"/>) that surface a missing
+    /// or already-deleted item as an error rather than treating it as a successful no-op.
+    /// </exception>
     Task DeleteTodoItemAsync(string id);
 }

samples/todoapp-blazor-wasm/TodoApp.BlazorWasm.Client/Services/TodoService.cs

@@ -76,7 +76,7 @@ public async Task<IEnumerable<TodoItemDto>> GetTodoItemsAsync()
     /// <summary>
     /// Creates a new todo item with the specified title.
     /// </summary>
-    /// <param name="title">The title or description of the new todo item.</param>
+    /// <param name="title">The title for the new todo item. Must not be null or empty.</param>
     /// <returns>
     /// A <see cref="Task{TResult}"/> that represents the asynchronous operation.
     /// The task result contains the newly created <see cref="TodoItemDto"/> with
@@ -90,11 +90,11 @@ public async Task<IEnumerable<TodoItemDto>> GetTodoItemsAsync()
     /// </para>
     /// <para>
     /// The method sends the new item to the server via the datasync client's 
-    /// <see cref="DatasyncServiceClient{T}.AddAsync(T)"/> method. Upon successful creation,
-    /// the server returns the persisted item with updated timestamps and version information.
+    /// <see cref="IDatasyncServiceClientExtensions.AddAsync{TEntity}(IDatasyncServiceClient{TEntity}, TEntity, CancellationToken)"/>
+    /// method. Upon successful creation, the server returns the persisted item with updated
+    /// timestamps and version information.
     /// </para>
     /// </remarks>
-    /// <param name="title">The title for the new todo item. Must not be null or empty.</param>
     /// <exception cref="ArgumentNullException">
     /// Thrown when <paramref name="title"/> is <c>null</c>.
     /// </exception>
@@ -104,8 +104,8 @@ public async Task<IEnumerable<TodoItemDto>> GetTodoItemsAsync()
     /// <exception cref="InvalidOperationException">
     /// Thrown when the server operation fails, containing details about the failure reason.
     /// </exception>
-    /// <exception cref="ValidationException">
-    /// Thrown when the todo item fails server-side validation (e.g., title too long).
+    /// <exception cref="ConflictException{TodoItemDto}">
+    /// Thrown when a todo item with the same identifier already exists in the remote service dataset.
     /// </exception>
     public async Task<TodoItemDto> CreateTodoItemAsync(string title)
     {
@@ -131,24 +131,28 @@ public async Task<TodoItemDto> CreateTodoItemAsync(string title)
     /// <remarks>
     /// <para>
     /// This method performs a complete replacement of the todo item on the server using
-    /// the datasync client's <see cref="DatasyncServiceClient{T}.ReplaceAsync(T)"/> method.
-    /// The operation includes optimistic concurrency control based on the item's version property.
+    /// the datasync client's <see cref="IDatasyncServiceClientExtensions.ReplaceAsync{TEntity}(IDatasyncServiceClient{TEntity}, TEntity, CancellationToken)"/>
+    /// method. The operation includes optimistic concurrency control based on the item's version property.
     /// </para>
     /// <para>
     /// 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 <see cref="ServiceResponse{T}"/> returned by the datasync client.
+    /// the server will reject the update with a conflict status, which is surfaced as a
+    /// <see cref="ConflictException{TodoItemDto}"/> by the datasync client.
     /// </para>
     /// </remarks>
     /// <exception cref="ArgumentNullException">
     /// Thrown when <paramref name="item"/> is <c>null</c>.
     /// </exception>
     /// <exception cref="InvalidOperationException">
-    /// 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.
     /// </exception>
-    /// <exception cref="ValidationException">
-    /// Thrown when the updated todo item fails server-side validation.
+    /// <exception cref="ConflictException{TodoItemDto}">
+    /// Thrown when the item has been modified by another client since it was last retrieved,
+    /// causing a version conflict.
+    /// </exception>
+    /// <exception cref="EntityDoesNotExistException">
+    /// Thrown when the item no longer exists on the server.
     /// </exception>
     public async Task<TodoItemDto> UpdateTodoItemAsync(TodoItemDto item)
     {
@@ -177,7 +181,7 @@ public async Task<TodoItemDto> UpdateTodoItemAsync(TodoItemDto item)
     /// </para>
     /// <para>
     /// The method uses <see cref="DatasyncServiceOptions"/> to configure the delete operation
-    /// and leverages the datasync client's <see cref="DatasyncServiceClient{T}.RemoveAsync(string, DatasyncServiceOptions)"/>
+    /// and leverages the datasync client's <see cref="DatasyncServiceClient{T}.RemoveAsync(string, DatasyncServiceOptions, CancellationToken)"/>
     /// method to perform the server-side operation.
     /// </para>
     /// <para>
@@ -192,9 +196,11 @@ public async Task<TodoItemDto> UpdateTodoItemAsync(TodoItemDto item)
     /// Thrown when <paramref name="id"/> is empty or whitespace only.
     /// </exception>
     /// <exception cref="InvalidOperationException">
-    /// 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.
+    /// </exception>
+    /// <exception cref="EntityDoesNotExistException">
+    /// Thrown when the item doesn't exist or has already been deleted on the server.
     /// </exception>
     public async Task DeleteTodoItemAsync(string id)
     {