docs: add more comments

Author: stainless-app[bot]

src/Orb/Core/ApiEnum.cs

@@ -5,18 +5,59 @@
 
 namespace Orb.Core;
 
+/// <summary>
+/// A serializable and deserializable enum wrapper type that handles the possibility of values outside the
+/// range of known enum members.
+///
+/// <para>In most cases you don't have to worry about this type and can rely on its implicit operators to
+/// wrap and unwrap enum values.</para>
+///
+/// <param name="Json">
+/// Returns this instance's raw value.
+///
+/// <para>This is usually only useful if this instance was deserialized from data that doesn't match the
+/// expected type (<typeparamref name="TRaw"/>), and you want to know that value. For example, if the
+/// SDK is on an older version than the API, then the API may respond with new data types that the SDK is
+/// unaware of.</para>
+/// </param>
+/// </summary>
 public record struct ApiEnum<TRaw, TEnum>(JsonElement Json)
     where TEnum : struct, Enum
 {
+    /// <summary>
+    /// Returns this instance's raw <typeparamref name="TRaw"/> value.
+    ///
+    /// <para>This is usually only useful if this instance was deserialized from data that doesn't match
+    /// any known enum member, and you want to know that value. For example, if the SDK is on an older
+    /// version than the API, then the API may respond with new members that the SDK is unaware of.</para>
+    ///
+    /// <exception cref="OrbInvalidDataException">
+    /// Thrown when this instance's raw value isn't of type <typeparamref name="TRaw"/>. Use
+    /// <see cref="Json"/> to access the raw value.
+    /// </exception>
+    /// </summary>
     public readonly TRaw Raw() =>
         JsonSerializer.Deserialize<TRaw>(this.Json, ModelBase.SerializerOptions)
         ?? throw new OrbInvalidDataException(
             string.Format("{0} cannot be null", nameof(this.Json))
         );
 
+    /// <summary>
+    /// Returns an enum member corresponding to this instance's value, or <c>(TEnum)(-1)</c> if the
+    /// class was instantiated with an unknown value.
+    ///
+    /// <para>Use <see cref="Raw"/> to access the raw <typeparamref name="TRaw"/> value.</para>.
+    /// </summary>
     public readonly TEnum Value() =>
         JsonSerializer.Deserialize<TEnum>(this.Json, ModelBase.SerializerOptions);
 
+    /// <summary>
+    /// Verifies that this instance's raw value is a member of <typeparamref name="TEnum"/>.
+    ///
+    /// <exception cref="OrbInvalidDataException">
+    /// Thrown when this instance's raw value isn't a member of <typeparamref name="TEnum"/>.
+    /// </exception>
+    /// </summary>
     public readonly void Validate()
     {
         if (!Enum.IsDefined(typeof(TEnum), Value()))

src/Orb/Core/ClientOptions.cs

@@ -4,27 +4,79 @@
 
 namespace Orb.Core;
 
+/// <summary>
+/// A class representing the SDK client configuration.
+/// </summary>
 public struct ClientOptions()
 {
+    /// <summary>
+    /// The default value used for <see cref="MaxRetries"/>.
+    /// </summary>
     public static readonly int DefaultMaxRetries = 2;
 
+    /// <summary>
+    /// The default value used for <see cref="Timeout"/>.
+    /// </summary>
     public static readonly TimeSpan DefaultTimeout = TimeSpan.FromMinutes(1);
 
+    /// <summary>
+    /// The HTTP client to use for making requests in the SDK.
+    /// </summary>
     public HttpClient HttpClient { get; set; } = new();
 
     Lazy<Uri> _baseUrl = new(() =>
         new Uri(Environment.GetEnvironmentVariable("ORB_BASE_URL") ?? "https://api.withorb.com/v1")
     );
+
+    /// <summary>
+    /// The base URL to use for every request.
+    ///
+    /// <para>Defaults to the production environment: https://api.withorb.com/v1</para>
+    /// </summary>
     public Uri BaseUrl
     {
         readonly get { return _baseUrl.Value; }
         set { _baseUrl = new(() => value); }
     }
 
+    /// <summary>
+    /// Whether to validate every response before returning it.
+    ///
+    /// <para>Defaults to false, which means the shape of the response will not be
+    /// validated upfront. Instead, validation will only occur for the parts of the
+    /// response that are accessed.</para>
+    /// </summary>
     public bool ResponseValidation { get; set; } = false;
 
+    /// <summary>
+    /// The maximum number of times to retry failed requests, with a short exponential backoff between requests.
+    ///
+    /// <para>
+    /// Only the following error types are retried:
+    /// <list type="bullet">
+    ///   <item>Connection errors (for example, due to a network connectivity problem)</item>
+    ///   <item>408 Request Timeout</item>
+    ///   <item>409 Conflict</item>
+    ///   <item>429 Rate Limit</item>
+    ///   <item>5xx Internal</item>
+    /// </list>
+    /// </para>
+    ///
+    /// <para>The API may also explicitly instruct the SDK to retry or not retry a request.</para>
+    ///
+    /// <para>Defaults to 2 when null. Set to 0 to
+    /// disable retries, which also ignores API instructions to retry.</para>
+    /// </summary>
     public int? MaxRetries { get; set; }
 
+    /// <summary>
+    /// Sets the maximum time allowed for a complete HTTP call, not including retries.
+    ///
+    /// <para>This includes resolving DNS, connecting, writing the request body, server processing, as
+    /// well as reading the response body.</para>
+    ///
+    /// <para>Defaults to <c>TimeSpan.FromMinutes(1)</c> when null.</para>
+    /// </summary>
     public TimeSpan? Timeout { get; set; }
 
     Lazy<string> _apiKey = new(() =>

src/Orb/Core/FreezableDictionary.cs

@@ -10,7 +10,7 @@ namespace Orb.Core;
 /// <summary>
 /// A dictionary that can be mutated and then frozen once no more mutations are expected.
 ///
-/// <para>This is useful for allowing a dictionary to be modified by a class's `init`
+/// <para>This is useful for allowing a dictionary to be modified by a class's <c>init</c>
 /// properties, but then preventing it from being modified afterwards.</para>
 /// </summary>
 class FreezableDictionary<K, V> : IDictionary<K, V>
@@ -43,6 +43,12 @@ public FreezableDictionary(FrozenDictionary<K, V> frozen)
         _dictionary = frozen;
     }
 
+    /// <summary>
+    /// Freezes this dictionary and returns a readonly view of it.
+    ///
+    /// <para>Future calls to mutating methods on this class will throw
+    /// <see cref="InvalidOperationException"/></para>.
+    /// </summary>
     public IReadOnlyDictionary<K, V> Freeze()
     {
         if (_dictionary is FrozenDictionary<K, V> dict)
@@ -56,77 +62,92 @@ public IReadOnlyDictionary<K, V> Freeze()
         return dictionary;
     }
 
+    /// <inheritdoc/>
     public V this[K key]
     {
         get => _dictionary[key];
         set => _mutableDictionary[key] = value;
     }
 
+    /// <inheritdoc/>
     public ICollection<K> Keys
     {
         get { return _dictionary.Keys; }
     }
 
+    /// <inheritdoc/>
     public ICollection<V> Values
     {
         get { return _dictionary.Values; }
     }
 
+    /// <inheritdoc/>
     public int Count
     {
         get { return _dictionary.Count; }
     }
 
+    /// <inheritdoc/>
     public bool IsReadOnly
     {
         get { return _dictionary.IsReadOnly; }
     }
 
+    /// <inheritdoc/>
     public void Add(K key, V value)
     {
         _mutableDictionary.Add(key, value);
     }
 
+    /// <inheritdoc/>
     public void Add(KeyValuePair<K, V> item)
     {
         _mutableDictionary.Add(item.Key, item.Value);
     }
 
+    /// <inheritdoc/>
     public void Clear()
     {
         _mutableDictionary.Clear();
     }
 
+    /// <inheritdoc/>
     public bool Contains(KeyValuePair<K, V> item)
     {
         return _dictionary.Contains(item);
     }
 
+    /// <inheritdoc/>
     public bool ContainsKey(K key)
     {
         return _dictionary.ContainsKey(key);
     }
 
+    /// <inheritdoc/>
     public void CopyTo(KeyValuePair<K, V>[] array, int arrayIndex)
     {
         _dictionary.CopyTo(array, arrayIndex);
     }
 
+    /// <inheritdoc/>
     public IEnumerator<KeyValuePair<K, V>> GetEnumerator()
     {
         return _dictionary.GetEnumerator();
     }
 
+    /// <inheritdoc/>
     public bool Remove(K key)
     {
         return _mutableDictionary.Remove(key);
     }
 
+    /// <inheritdoc/>
     public bool Remove(KeyValuePair<K, V> item)
     {
         return _mutableDictionary.Remove(item.Key);
     }
 
+    /// <inheritdoc/>
     public bool TryGetValue(K key,
 #if NET
         [MaybeNullWhen(false)]
@@ -137,6 +158,7 @@ public bool TryGetValue(K key,
         return _dictionary.TryGetValue(key, out value);
     }
 
+    /// <inheritdoc/>
     Collections::IEnumerator Collections::IEnumerable.GetEnumerator()
     {
         return _dictionary.GetEnumerator();

src/Orb/IOrbClient.cs

@@ -8,26 +8,80 @@
 namespace Orb;
 
 /// <summary>
-/// NOTE: Do not inherit from this type outside the SDK unless you're okay with breaking
-/// changes in non-major versions. We may add new methods in the future that cause
-/// existing derived classes to break.
+/// A client for interacting with the Orb REST API.
+///
+/// <para>This client performs best when you create a single instance and reuse it
+/// for all interactions with the REST API. This is because each client holds its
+/// own connection pool and thread pools. Reusing connections and threads reduces
+/// latency and saves memory.</para>
+///
+/// <para>NOTE: Do not inherit from this type outside the SDK unless you're okay with
+/// breaking changes in non-major versions. We may add new methods in the future that
+/// cause existing derived classes to break.</para>
 /// </summary>
 public interface IOrbClient
 {
+    /// <summary>
+    /// The HTTP client to use for making requests in the SDK.
+    /// </summary>
     HttpClient HttpClient { get; init; }
 
+    /// <summary>
+    /// The base URL to use for every request.
+    ///
+    /// <para>Defaults to the production environment: https://api.withorb.com/v1</para>
+    /// </summary>
     Uri BaseUrl { get; init; }
 
+    /// <summary>
+    /// Whether to validate every response before returning it.
+    ///
+    /// <para>Defaults to false, which means the shape of the response will not be
+    /// validated upfront. Instead, validation will only occur for the parts of the
+    /// response that are accessed.</para>
+    /// </summary>
     bool ResponseValidation { get; init; }
 
+    /// <summary>
+    /// The maximum number of times to retry failed requests, with a short exponential backoff between requests.
+    ///
+    /// <para>
+    /// Only the following error types are retried:
+    /// <list type="bullet">
+    ///   <item>Connection errors (for example, due to a network connectivity problem)</item>
+    ///   <item>408 Request Timeout</item>
+    ///   <item>409 Conflict</item>
+    ///   <item>429 Rate Limit</item>
+    ///   <item>5xx Internal</item>
+    /// </list>
+    /// </para>
+    ///
+    /// <para>The API may also explicitly instruct the SDK to retry or not retry a request.</para>
+    ///
+    /// <para>Defaults to 2 when null. Set to 0 to
+    /// disable retries, which also ignores API instructions to retry.</para>
+    /// </summary>
     int? MaxRetries { get; init; }
 
+    /// <summary>
+    /// Sets the maximum time allowed for a complete HTTP call, not including retries.
+    ///
+    /// <para>This includes resolving DNS, connecting, writing the request body, server processing, as
+    /// well as reading the response body.</para>
+    ///
+    /// <para>Defaults to <c>TimeSpan.FromMinutes(1)</c> when null.</para>
+    /// </summary>
     TimeSpan? Timeout { get; init; }
 
     string APIKey { get; init; }
 
     string? WebhookSecret { get; init; }
 
+    /// <summary>
+    /// Returns a view of this service with the given option modifications applied.
+    ///
+    /// <para>The original service is not modified.</para>
+    /// </summary>
     IOrbClient WithOptions(Func<ClientOptions, ClientOptions> modifier);
 
     ITopLevelService TopLevel { get; }
@@ -62,6 +116,9 @@ public interface IOrbClient
 
     ISubscriptionChangeService SubscriptionChanges { get; }
 
+    /// <summary>
+    /// Sends a request to the Orb REST API.
+    /// </summary>
     Task<HttpResponse> Execute<T>(
         HttpRequest<T> request,
         CancellationToken cancellationToken = default