Update docs

Author: w1am

docs/api/appending-events.md

@@ -146,38 +146,6 @@ This feature is only available in KurrentDB 25.1 and later.
 
 You can append events to multiple streams in a single atomic operation. Either all streams are updated, or the entire operation fails.
 
-The `MultiStreamAppendAsync` method accepts a collection of `AppendStreamRequest` objects and returns a `MultiAppendWriteResult`. Each `AppendStreamRequest` contains:
-
-- **Stream** - The name of the stream
-- **ExpectedState** - The expected state of the stream for optimistic concurrency control
-- **Messages** - A collection of `EventData` objects to append
-
-The operation returns either:
-- `MultiAppendSuccess` - Successful append results for all streams
-- `MultiAppendFailure` - Specific exceptions for any failed operations
-
-::: warning
-Event metadata in `EventData` must currently be valid JSON that can be deserialized into a
-`Dictionary<string, object?>`. This means any metadata you attach to an event should be structured as a JSON object, not as a primitive value or array.
-
-For example, to encode metadata:
-```cs
-var metadata = JsonSerializer.SerializeToUtf8Bytes(new {
-	Timestamp = DateTime.UtcNow,
-	Source = "OrderProcessingSystem",
-	Version = 1.0
-});
-```
-To decode metadata back into a dictionary:
-```cs
-var dictionary = MetadataDecoder.Decode(metadataBytes);
-```
-
-This requirement ensures compatibility with KurrentDB's current metadata handling. In a future major release, this restriction will be lifted, allowing more flexible metadata formats.
-:::
-
-Here's a basic example of appending events to multiple streams:
-
 ```cs
 using System.Text.Json;
 
@@ -198,41 +166,19 @@ AppendStreamRequest[] requests = [
 	)
 ];
 
-var result = await client.MultiStreamAppendAsync(requests);
-
-if (result is MultiAppendSuccess { Successes: var successes })
-	foreach (var item in successes)
-		Console.WriteLine($"Stream '{item.Stream}' updated at position {item.Position}");
+await client.MultiStreamAppendAsync(requests);
 ```
 
-If the operation doesn't succeed, you should check if the result is a `MultiAppendFailure` and handle each failure case appropriately. This allows you to respond to specific errors, such as version conflicts, access issues, deleted streams, or transaction size limits. For example:
+The result returns the position of the last appended record in the transaction and a collection of responses for each stream appended in the transaction.
 
+::: warning
+If you are storing metadata, it must currently be a valid JSON that can be deserialized into a
+`Dictionary<string, object?>`. This means any metadata you attach to an event should be structured as a JSON object, not as a primitive value or array.
+
+When reading those events you can use the metadata decoder utility class to decode your metadata:
 ```cs
-var result = await client.MultiStreamAppendAsync(requests);
-
-if (result is MultiAppendFailure { Failures: var failures }) {
-	foreach (var error in failures) {
-		switch (error) {
-			case WrongExpectedVersionException ex:
-				Console.WriteLine($"Version conflict in stream: {ex.Message}");
-				break;
-
-			case AccessDeniedException:
-				Console.WriteLine("Access denied to one or more streams");
-				break;
-
-			case StreamDeletedException ex:
-				Console.WriteLine($"Stream was deleted: {ex.Message}");
-				break;
-
-			case TransactionMaxSizeExceededException ex:
-				Console.WriteLine($"Transaction too large: {ex.Message}");
-				break;
-
-			default:
-				Console.WriteLine($"Unexpected error: {error.Message}");
-				break;
-		}
-	}
-}
+var dictionary = MetadataDecoder.Decode(metadataBytes);
 ```
+
+This requirement ensures compatibility with KurrentDB's current metadata handling, and the restriction will be lifted in the next major release.
+:::

src/KurrentDB.Client/Streams/Streams/Model/StreamsClientModel.cs

@@ -20,11 +20,27 @@ namespace KurrentDB.Client;
 [PublicAPI]
 public record AppendStreamRequest(string Stream, StreamState ExpectedState, IEnumerable<EventData> Messages);
 
+/// <summary>
+/// Represents the outcome of an append operation.
+/// </summary>
+/// <param name="Stream">
+/// The name of the stream to which records were appended.
+/// </param>
+/// <param name="StreamRevision">
+/// The expected revision of the stream after the append operation.
+/// </param>
 [PublicAPI]
 public record AppendResponse(string Stream, long StreamRevision);
 
 [PublicAPI]
 public readonly struct MultiStreamAppendResponse(long position, IEnumerable<AppendResponse>? responses = null) {
-	public readonly long                         Position  = position;
+	/// <summary>
+	/// The position of the last appended record in the transaction.
+	/// </summary>
+	public readonly long Position = position;
+
+	/// <summary>
+	/// The collection of responses for each stream appended in the transaction.
+	/// </summary>
 	public readonly IEnumerable<AppendResponse>? Responses = responses;
 }