add XML comments

Author: Cuong Pham

StellarDotnetSdk/Claimants/ClaimPredicate.cs

@@ -3,6 +3,29 @@
 
 namespace StellarDotnetSdk.Claimants;
 
+/// <summary>
+///     Represents a claim predicate for building claimable balance operations in Stellar transactions.
+/// </summary>
+/// <remarks>
+///     <para>
+///         This abstract class and its implementations are used when constructing
+///         <see cref="StellarDotnetSdk.Operations.CreateClaimableBalanceOperation"/> to define
+///         conditions under which a claimable balance can be claimed.
+///     </para>
+///     <para>
+///         Predicates can be combined using logical operators:
+///         <list type="bullet">
+///             <item><see cref="And"/> - Both predicates must be true</item>
+///             <item><see cref="Or"/> - At least one predicate must be true</item>
+///             <item><see cref="Not"/> - The predicate must be false</item>
+///         </list>
+///     </para>
+///     <para>
+///         <strong>For deserializing Horizon API responses</strong>, use <see cref="Responses.Predicate"/> instead,
+///         which can be converted to this type using <see cref="Responses.Predicate.ToClaimPredicate"/>.
+///     </para>
+/// </remarks>
+/// <seealso cref="Responses.Predicate"/>
 public abstract class ClaimPredicate
 {
     public abstract Xdr.ClaimPredicate ToXdr();

StellarDotnetSdk/Claimants/Claimant.cs

@@ -3,22 +3,35 @@
 
 namespace StellarDotnetSdk.Claimants;
 
+/// <summary>
+///     Represents a claimant for building claimable balance operations in Stellar transactions.
+/// </summary>
+/// <remarks>
+///     <para>
+///         This class is used when constructing <see cref="StellarDotnetSdk.Operations.CreateClaimableBalanceOperation"/>
+///         to specify who can claim the balance and under what conditions.
+///     </para>
+///     <para>
+///         <strong>For deserializing Horizon API responses</strong>, use <see cref="Responses.Claimant"/> instead.
+///     </para>
+/// </remarks>
+/// <seealso cref="Responses.Claimant"/>
 public class Claimant
 {
     /// <summary>
     ///     Constructs a <c>Claimant</c> object from a public key and a predicate.
     /// </summary>
     /// <param name="recipientId">An Ed25519 public key.</param>
-    /// <param name="predicate">A <c>Predicate</c> object.</param>
+    /// <param name="predicate">A <see cref="ClaimPredicate"/> defining when this claimant can claim the balance.</param>
     public Claimant(string recipientId, ClaimPredicate predicate) : this(KeyPair.FromAccountId(recipientId), predicate)
     {
     }
 
     /// <summary>
     ///     Constructs a <c>Claimant</c> object from a key pair and a predicate.
     /// </summary>
-    /// <param name="recipientId">An Ed25519 public key.</param>
-    /// <param name="predicate">A <c>Predicate</c> object.</param>
+    /// <param name="destination">The destination account that can claim the balance.</param>
+    /// <param name="predicate">A <see cref="ClaimPredicate"/> defining when this claimant can claim the balance.</param>
     public Claimant(KeyPair destination, ClaimPredicate predicate)
     {
         Destination = destination;

StellarDotnetSdk/Responses/Claimant.cs

@@ -3,6 +3,21 @@
 namespace StellarDotnetSdk.Responses;
 #nullable disable
 
+/// <summary>
+///     Represents a claimant in Horizon API responses.
+/// </summary>
+/// <remarks>
+///     <para>
+///         This class is specifically designed for deserializing claimant data from Horizon API responses,
+///         such as when querying claimable balances.
+///     </para>
+///     <para>
+///         <strong>For building transactions</strong>, use <see cref="Claimants.Claimant"/> instead.
+///         You can convert the <see cref="Predicate"/> to a transaction predicate using
+///         <see cref="Predicate.ToClaimPredicate"/>.
+///     </para>
+/// </remarks>
+/// <seealso cref="Claimants.Claimant"/>
 public class Claimant
 {
     [JsonPropertyName("destination")]

StellarDotnetSdk/Responses/Predicate.cs

@@ -6,9 +6,24 @@
 namespace StellarDotnetSdk.Responses;
 
 /// <summary>
-///     Represents a claim predicate that defines conditions for claiming a claimable balance.
-///     Predicates can be combined using logical operators (AND, OR, NOT) or specify time-based conditions.
+///     Represents a claim predicate in Horizon API responses.
 /// </summary>
+/// <remarks>
+///     <para>
+///         This class is specifically designed for deserializing predicate data from Horizon API responses.
+///         It uses <see cref="long"/> for time-based fields to accommodate values returned by Horizon endpoints.
+///     </para>
+///     <para>
+///         The Horizon API may return numeric fields as strings in some cases. The SDK's
+///         <see cref="Converters.JsonOptions.DefaultOptions"/> handles both formats automatically
+///         via <c>JsonNumberHandling.AllowReadingFromString</c>.
+///     </para>
+///     <para>
+///         <strong>For building transactions</strong>, use <see cref="Claimants.ClaimPredicate"/> instead.
+///         You can convert this response predicate to a transaction predicate using <see cref="ToClaimPredicate"/>.
+///     </para>
+/// </remarks>
+/// <seealso cref="Claimants.ClaimPredicate"/>
 public sealed class Predicate
 {
     /// <summary>