Merge pull request #50 from AssemblyAI/niels/add-xml-docs

feat: Add XML docs

README.md

@@ -258,7 +258,6 @@ while(page.PageDetails.PrevUrl != null)
 <details>
 <summary>Delete a transcript</summary>
 
-
 ```csharp
 var transcript = await client.Transcripts.DeleteAsync(transcript.Id);
 ```

src/AssemblyAI.IntegrationTests/TranscriptsClientTests.cs

@@ -217,7 +217,7 @@ public async Task Should_Transcribe_Using_Stream_With_Dispose()
         var testFilePath = Path.Combine(TestContext.CurrentContext.TestDirectory, "TestData", "nbc.mp3");
         var stream = File.OpenRead(testFilePath);
 
-        var transcript = await client.Transcripts.TranscribeAsync(stream, disposeStream: true).ConfigureAwait(false);
+        var transcript = await client.Transcripts.TranscribeAsync(stream, disposeStream: true, new TranscriptOptionalParams()).ConfigureAwait(false);
 
         Assert.That(transcript, Is.Not.Null);
         Assert.Multiple(() =>

src/AssemblyAI/AssemblyAIClient.cs

@@ -8,23 +8,40 @@
 
 namespace AssemblyAI;
 
+/// <summary>
+/// The client to interact with the AssemblyAI API.
+/// </summary>
 public class AssemblyAIClient
 {
+    /// <inheritdoc cref="FilesClient"/>
     public FilesClient Files { get; private init; }
 
+    /// <inheritdoc cref="ExtendedTranscriptsClient"/>
     public ExtendedTranscriptsClient Transcripts { get; private init; }
 
+    /// <inheritdoc cref="RealtimeClient"/>
     public RealtimeClient Realtime { get; private init; }
 
+    /// <inheritdoc cref="LemurClient"/>
     public LemurClient Lemur { get; private init; }
 
+    /// <summary>
+    /// Create a new instance of the <see cref="AssemblyAIClient"/> class.
+    /// </summary>
+    /// <param name="apiKey">Your AssemblyAI API key</param>
+    /// <exception cref="ArgumentException">Thrown if apiKey is null or empty.</exception>
     public AssemblyAIClient(string apiKey) : this(new ClientOptions
     {
         ApiKey = apiKey
     })
     {
     }
 
+    /// <summary>
+    /// Create a new instance of the <see cref="AssemblyAIClient"/> class.
+    /// </summary>
+    /// <param name="clientOptions">The AssemblyAI client options</param>
+    /// <exception cref="ArgumentException">Thrown if ClientOptions.ApiKey is null or empty.</exception>
     public AssemblyAIClient(ClientOptions clientOptions)
     {
         if (string.IsNullOrEmpty(clientOptions.ApiKey))

src/AssemblyAI/Core/CustomConstants.cs

@@ -2,5 +2,9 @@ namespace AssemblyAI.Core;
 
 internal static class CustomConstants
 {
+    /// <summary>
+    /// This is used for the AssemblyAI User-Agent.
+    /// If you update this, make sure to also update the version numbers in AssemblyAI.csproj
+    /// </summary>
     internal const string Version = "1.1.0";
 }

src/AssemblyAI/Core/JsonConfiguration.cs

@@ -5,8 +5,14 @@
 
 namespace AssemblyAI.Core;
 
+/// <summary>
+/// The JSON options used by the AssemblyAI SDK.
+/// </summary>
 internal static class JsonOptions
 {
+    /// <summary>
+    /// The JSON options used by the AssemblyAI SDK.
+    /// </summary>
     internal static readonly JsonSerializerOptions JsonSerializerOptions;
 
     static JsonOptions()
@@ -24,13 +30,28 @@ static JsonOptions()
     }
 }
 
+/// <summary>
+/// Utilities class for JSON serialization and deserialization.
+/// </summary>
 internal static class JsonUtils
 {
+    /// <summary>
+    /// Serialize an object to JSON using the AssemblyAI SDK's JSON options.
+    /// </summary>
+    /// <param name="obj">Object to serialize</param>
+    /// <typeparam name="T">Type of the object to serialize</typeparam>
+    /// <returns>The object serialized as JSON</returns>
     internal static string Serialize<T>(T obj)
     {
         return JsonSerializer.Serialize(obj, JsonOptions.JsonSerializerOptions);
     }
 
+    /// <summary>
+    /// Deserialize a JSON string to an object using the AssemblyAI SDK's JSON options.
+    /// </summary>
+    /// <param name="json">The JSON string</param>
+    /// <typeparam name="T">The type to deserialize the JSON to</typeparam>
+    /// <returns>The deserialized object of type T</returns>
     internal static T Deserialize<T>(string json)
     {
         return JsonSerializer.Deserialize<T>(json, JsonOptions.JsonSerializerOptions)!;

src/AssemblyAI/Core/Public/ApiException.cs

@@ -35,6 +35,11 @@ internal ApiException(string message, int statusCode, object body)
     }
 
     // TODO: Remove when Fern generator can set this property
+    /// <summary>
+    /// Serialize the HTTP response body to a string.
+    /// </summary>
+    /// <param name="body">The HTTP response body</param>
+    /// <returns>The serialized HTTP response body</returns>
     private static string GetResponseContentFromBody(object body)
     {
         return body switch
@@ -45,6 +50,12 @@ private static string GetResponseContentFromBody(object body)
         };
     }
 
+    /// <summary>
+    /// Retrieves the error message from the JSON body of the response.
+    /// </summary>
+    /// <param name="message">The default error message to fallback to</param>
+    /// <param name="body">The HTTP response body</param>
+    /// <returns>The error message</returns>
     private static string GetMessageFromJsonBody(string message, object body)
     {
         if (body is not string stringBody) return message;

src/AssemblyAI/Core/Public/AssemblyAIClientEnvironment.cs

@@ -1,6 +1,13 @@
+// ReSharper disable CheckNamespace
 namespace AssemblyAI;
 
-public class AssemblyAIClientEnvironment
+/// <summary>
+/// Available AssemblyAI API environments
+/// </summary>
+public static class AssemblyAIClientEnvironment
 {
-    public static string Default = "https://api.assemblyai.com";
+    /// <summary>
+    /// The default base URL for the AssemblyAI API.
+    /// </summary>
+    public const string Default = "https://api.assemblyai.com";
 }

src/AssemblyAI/Core/Public/ClientOptions.cs

@@ -1,8 +1,6 @@
-using System;
 using System.Net.Http;
 using AssemblyAI.Core;
-
-#nullable enable
+// ReSharper disable CheckNamespace
 
 namespace AssemblyAI;
 
@@ -16,7 +14,7 @@ public partial class ClientOptions
     /// <summary>
     /// The http client used to make requests.
     /// </summary>
-    public HttpClient HttpClient { get; set; } = new HttpClient();
+    public HttpClient HttpClient { get; set; } = new();
 
     /// <summary>
     /// The amount to retry sending the HTTP request if it fails.

src/AssemblyAI/Core/Public/ExtendedClientOptions.cs

@@ -1,8 +1,12 @@
+// ReSharper disable PartialTypeWithSinglePart
 // ReSharper disable AutoPropertyCanBeMadeGetOnly.Global
 // ReSharper disable CheckNamespace
 
 namespace AssemblyAI;
 
+/// <summary>
+/// The options for the AssemblyAI client.
+/// </summary>
 public partial class ClientOptions
 {
     /// <summary>

src/AssemblyAI/Core/Public/ExtendedRequestOptions.cs

@@ -0,0 +1,9 @@
+// ReSharper disable CheckNamespace
+// ReSharper disable ClassNeverInstantiated.Global
+
+namespace AssemblyAI;
+
+/// <summary>
+/// The options for one or multiple requests to the AssemblyAI API.
+/// </summary>
+public partial class RequestOptions;

src/AssemblyAI/DependencyInjectionExtensions.cs

@@ -6,10 +6,19 @@
 
 namespace AssemblyAI;
 
+/// <summary>
+/// Extensions to add the AssemblyAI client to the service collection.
+/// </summary>
 public static class DependencyInjectionExtensions
 {
     private const string AssemblyAIHttpClientName = "AssemblyAI";
 
+    /// <summary>
+    /// Add the AssemblyAI client to the service collection.
+    /// The AssemblyAI options are configured using the "AssemblyAI" section.
+    /// </summary>
+    /// <param name="services">The service collection</param>
+    /// <returns>The service collection</returns>
     public static IServiceCollection AddAssemblyAIClient(this IServiceCollection services)
     {
         var optionsBuilder = services.AddOptions<ClientOptions>();
@@ -19,6 +28,12 @@ public static IServiceCollection AddAssemblyAIClient(this IServiceCollection ser
         return services;
     }
 
+    /// <summary>
+    /// Add the AssemblyAI client to the service collection.
+    /// </summary>
+    /// <param name="services">The service collection</param>
+    /// <param name="namedConfigurationSection">The section where the AssemblyAI options are configured.</param>
+    /// <returns>The service collection</returns>
     public static IServiceCollection AddAssemblyAIClient(
         this IServiceCollection services,
         IConfiguration namedConfigurationSection
@@ -31,13 +46,19 @@ IConfiguration namedConfigurationSection
         return services;
     }
 
+    /// <summary>
+    /// Add the AssemblyAI client to the service collection.
+    /// </summary>
+    /// <param name="services">The service collection</param>
+    /// <param name="configureOptions">Configure the client options using this callback.</param>
+    /// <returns>The service collection</returns>
     public static IServiceCollection AddAssemblyAIClient(
         this IServiceCollection services,
         Action<ClientOptions> configureOptions
     )
         => AddAssemblyAIClient(services, (_, options) => configureOptions(options));
 
-
+    /// <inheritdoc cref="AddAssemblyAIClient(IServiceCollection,Action{ClientOptions})"/>
     public static IServiceCollection AddAssemblyAIClient(
         this IServiceCollection services,
         Action<IServiceProvider, ClientOptions> configureOptions
@@ -50,7 +71,12 @@ Action<IServiceProvider, ClientOptions> configureOptions
         return services;
     }
 
-
+    /// <summary>
+    /// Add the AssemblyAI client to the service collection.
+    /// </summary>
+    /// <param name="services">The service collection</param>
+    /// <param name="options">The AssemblyAI client options.</param>
+    /// <returns>The service collection</returns>
     public static IServiceCollection AddAssemblyAIClient(
         this IServiceCollection services,
         ClientOptions options

src/AssemblyAI/EnumConverter.cs

@@ -2,6 +2,9 @@
 
 namespace AssemblyAI;
 
+/// <summary>
+/// Convert an AssemblyAI enum to a string and vice versa.
+/// </summary>
 public static class EnumConverter
 {
     /// <summary>

src/AssemblyAI/Event.cs

@@ -27,16 +27,24 @@ internal async Task RaiseEvent(T eventObject)
         }
     }
 
+    /// <summary>
+    /// Subscribe to the event
+    /// </summary>
     public void Subscribe(Action<T> eventHandler)
     {
         _subscribers.Add(eventHandler);
     }
 
+    /// <inheritdoc cref="Subscribe(System.Action{T})"/>
     public void Subscribe(Func<T, Task> eventHandler)
     {
         _subscribersAsync.Add(eventHandler);
     }
 
+    /// <summary>
+    /// Unsubscribe from the event
+    /// </summary>
+    /// <param name="eventHandler"></param>
     public void Unsubscribe(Action<T> eventHandler)
     {
         if (_subscribers.Contains(eventHandler))
@@ -45,6 +53,7 @@ public void Unsubscribe(Action<T> eventHandler)
         }
     }
 
+    /// <inheritdoc cref="Unsubscribe(System.Action{T})"/>
     public void Unsubscribe(Func<T, Task> eventHandler)
     {
         if (_subscribersAsync.Contains(eventHandler))
@@ -53,11 +62,18 @@ public void Unsubscribe(Func<T, Task> eventHandler)
         }
     }
 
+    /// <summary>
+    /// Unsubscribe all event handlers
+    /// </summary>
     public void UnsubscribeAll()
     {
         _subscribers.Clear();
         _subscribersAsync.Clear();
     }
-
+
+    /// <summary>
+    /// Dispose of the event.
+    /// Unsubscribes all event handlers.
+    /// </summary>
     public void Dispose() => UnsubscribeAll();
 }

src/AssemblyAI/Files/ExtendedFilesClient.cs

@@ -1,10 +1,17 @@
 namespace AssemblyAI.Files;
 
+/// <summary>
+/// Client to upload files to the AssemblyAI API.
+/// </summary>
 public partial class FilesClient
 {
     /// <summary>
     /// Upload a media file to AssemblyAI's servers.
     /// </summary>
+    /// <param name="audioFile">The local file to upload</param>
+    /// <param name="options">The HTTP request options</param>
+    /// <param name="cancellationToken"></param>
+    /// <returns>File uploaded to AssemblyAI</returns>
     public async Task<UploadedFile> UploadAsync(
         FileInfo audioFile,
         RequestOptions? options = null,
@@ -23,6 +30,11 @@ public async Task<UploadedFile> UploadAsync(
     /// <summary>
     /// Upload a media file to AssemblyAI's servers.
     /// </summary>
+    /// <param name="stream">The file stream to upload</param>
+    /// <param name="disposeStream">Dispose the stream ASAP</param>
+    /// <param name="options">The HTTP request options</param>
+    /// <param name="cancellationToken"></param>
+    /// <returns>File uploaded to AssemblyAI</returns>
     public async Task<UploadedFile> UploadAsync(
         Stream stream,
         bool disposeStream,

src/AssemblyAI/Lemur/ExtendedLemurClient.cs

@@ -0,0 +1,6 @@
+namespace AssemblyAI.Lemur;
+
+/// <summary>
+/// The client to interact with the AssemblyAI LeMUR API.
+/// </summary>
+public partial class LemurClient;

src/AssemblyAI/Realtime/ExtendedRealtimeClient.cs

@@ -2,6 +2,10 @@
 
 namespace AssemblyAI.Realtime;
 
+/// <summary>
+/// The client to interact with the AssemblyAI Realtime HTTP API.
+/// To interact with the Realtime WebSocket API, use the <see cref="RealtimeTranscriber"/> class.
+/// </summary>
 public partial class RealtimeClient
 {
     /// <summary>