From 5d00b45111b7b73e4e82f81f98a2274788375a14 Mon Sep 17 00:00:00 2001 From: Patchouli Date: Sat, 2 Nov 2024 13:55:16 -0400 Subject: [PATCH] Added inline documentation --- source/Kagi/KagiAnswerData.cs | 10 +- source/Kagi/KagiAnswerDataReference.cs | 8 +- source/Kagi/KagiAnswerOptions.cs | 9 +- source/Kagi/KagiAnswerResult.cs | 4 +- source/Kagi/KagiClient.cs | 169 +++++++++++-------- source/Kagi/KagiError.cs | 8 +- source/Kagi/KagiErrorCode.cs | 2 +- source/Kagi/KagiErrorResult.cs | 4 +- source/Kagi/KagiException.cs | 31 ++-- source/Kagi/KagiRecordSearchData.cs | 14 +- source/Kagi/KagiRecordSearchDataThumbnail.cs | 12 +- source/Kagi/KagiRelatedQuerySearchData.cs | 6 +- source/Kagi/KagiResult.cs | 4 +- source/Kagi/KagiResultMetadata.cs | 10 +- source/Kagi/KagiSearchData.cs | 10 +- source/Kagi/KagiSearchDataType.cs | 7 +- source/Kagi/KagiSearchResult.cs | 4 +- source/Kagi/KagiSummarizeData.cs | 7 +- source/Kagi/KagiSummarizeOptions.cs | 26 ++- source/Kagi/KagiSummarizeResult.cs | 4 +- source/Kagi/KagiSummaryEngine.cs | 8 +- source/Kagi/KagiSummaryKind.cs | 6 +- source/Kagi/KagiSummaryLanguage.cs | 62 +++---- source/Kagi/KagiUrlHelper.cs | 30 +++- 24 files changed, 257 insertions(+), 198 deletions(-) diff --git a/source/Kagi/KagiAnswerData.cs b/source/Kagi/KagiAnswerData.cs index d9dd686..290066b 100644 --- a/source/Kagi/KagiAnswerData.cs +++ b/source/Kagi/KagiAnswerData.cs @@ -8,26 +8,28 @@ namespace Kagi { /// - /// + /// Represents the response data for a + /// . /// public class KagiAnswerData { /// - /// + /// The answer output. /// [JsonPropertyName( "output")] public string Output { get; init; } /// - /// + /// A collection of + /// search records that were utilized to produce the answer output. /// [JsonPropertyName( "references")] public ImmutableArray References { get; init; } /// - /// + /// The number of tokens processed to produce the answer output. /// [JsonPropertyName( "tokens")] diff --git a/source/Kagi/KagiAnswerDataReference.cs b/source/Kagi/KagiAnswerDataReference.cs index 1842b75..80f4f9e 100644 --- a/source/Kagi/KagiAnswerDataReference.cs +++ b/source/Kagi/KagiAnswerDataReference.cs @@ -6,26 +6,26 @@ namespace Kagi { /// - /// + /// Represents a search record that was utilized to produce the output for an answer. /// public class KagiAnswerDataReference { /// - /// + /// The title of the referenced search record. /// [JsonPropertyName( "title")] public string Title { get; init; } /// - /// + /// The snippet of the referenced search record, if any. /// [JsonPropertyName( "Snippet")] public string Snippet { get; init; } /// - /// + /// The URL of the referenced search record. /// [JsonPropertyName( "url")] diff --git a/source/Kagi/KagiAnswerOptions.cs b/source/Kagi/KagiAnswerOptions.cs index 0ee93be..476b6dc 100644 --- a/source/Kagi/KagiAnswerOptions.cs +++ b/source/Kagi/KagiAnswerOptions.cs @@ -6,22 +6,23 @@ namespace Kagi { /// - /// + /// Represents the options for an answer operation. /// public class KagiAnswerOptions { /// - /// + /// The query to be answered. /// [JsonPropertyName( "query")] public string Query { get; init; } /// - /// + /// Whether to allow cached requests and responses. /// [JsonPropertyName( "cache")] - public bool AllowCaching { get; init; } + public bool AllowCaching { get; init; } = + true; } } diff --git a/source/Kagi/KagiAnswerResult.cs b/source/Kagi/KagiAnswerResult.cs index 3b9cbaa..199bc90 100644 --- a/source/Kagi/KagiAnswerResult.cs +++ b/source/Kagi/KagiAnswerResult.cs @@ -6,13 +6,13 @@ namespace Kagi { /// - /// + /// Represents the result of an answer operation. /// public class KagiAnswerResult : KagiResult { /// - /// + /// The response data for the result. /// [JsonPropertyName( "data")] diff --git a/source/Kagi/KagiClient.cs b/source/Kagi/KagiClient.cs index b2a79e7..51d5ba1 100644 --- a/source/Kagi/KagiClient.cs +++ b/source/Kagi/KagiClient.cs @@ -19,19 +19,19 @@ public sealed class KagiClient : IDisposable { /// - /// + /// The base URL for the Kagi API. /// private const string DefaultBaseUrlValue = "https://kagi.com/api/v0/"; /// - /// + /// Gets the default base URL for a . /// public static Uri DefaultBaseUrl { get; } = new Uri(DefaultBaseUrlValue); /// - /// + /// The JSON serializer options for serializing and deserializing JSON data. /// private static JsonSerializerOptions JsonSerializerOptions { get; } = new JsonSerializerOptions() @@ -41,11 +41,11 @@ public sealed class KagiClient : }; /// - /// + /// Creates an instance of HttpClient with the specified base URL and API key. /// - /// - /// - /// + /// The base URL for the API. + /// The API key used for authorization. + /// A configured HttpClient instance. private static HttpClient CreateClient( Uri baseUrl, string apiKey) @@ -62,8 +62,11 @@ private static HttpClient CreateClient( var client = new HttpClient(); + // Set the base URL for the client to use. client.BaseAddress = baseUrl; + + // Set the 'Authorization' header value. client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue( "Bot", @@ -73,20 +76,23 @@ private static HttpClient CreateClient( } /// - /// + /// Processes the HTTP response, deserializing it into a result or throwing an exception if the response contains an error. /// - /// - /// - /// - /// - /// + /// Type of result expected from the response. + /// The HTTP response message. + /// Token to observe while waiting for the task to complete. + /// A task that represents the asynchronous operation, containing the result. + /// Thrown if the response contains an error. private static async Task ProcessResponseAsync( HttpResponseMessage response, CancellationToken cancellationToken = default) where TResult : KagiResult { + // Check the status code for the response. if (response.StatusCode == HttpStatusCode.OK) { + // Read the successful result from the response body. + // TODO: Should exception handling here be more robust(?) var result = await response.Content .ReadFromJsonAsync( @@ -97,6 +103,7 @@ await response.Content } else { + // Read the error result from the response body. var errorResult = await response.Content .ReadFromJsonAsync( @@ -114,7 +121,7 @@ await response.Content private volatile bool isDisposed; /// - /// + /// Gets the base URL used by the client. /// public Uri BaseUrl { @@ -131,7 +138,7 @@ public Uri BaseUrl } /// - /// + /// Gets the authorization header value set on the client. /// public AuthenticationHeaderValue AuthorizationHeaderValue { @@ -149,9 +156,10 @@ public AuthenticationHeaderValue AuthorizationHeaderValue } /// - /// + /// Initializes a new instance of the + /// class with the specified API key. /// - /// + /// The API key for authorizing requests. public KagiClient( string apiKey) : this( @@ -160,10 +168,11 @@ public KagiClient( { } /// - /// + /// Initializes a new instance of the + /// class with the specified base URL and API key. /// - /// - /// + /// The base URL for the API. + /// The API key for authorizing requests. public KagiClient( Uri baseUrl, string apiKey) : @@ -175,10 +184,11 @@ public KagiClient( { } /// - /// + /// Initializes a new instance of the + /// class with a specified and ownership flag. /// - /// - /// + /// The instance to use. + /// Specifies whether the client should dispose the HttpClient instance. public KagiClient( HttpClient client, bool ownsClient = false) @@ -193,12 +203,12 @@ public KagiClient( } /// - /// + /// Sends a summarization request to Kagi. /// - /// - /// - /// - /// + /// The options for summarization. + /// Token to observe while waiting for the task to complete. + /// A task that represents the asynchronous operation, containing the summarization result. + /// Thrown if the request fails. public async Task SummarizeAsync( KagiSummarizeOptions options, CancellationToken cancellationToken = default) @@ -213,6 +223,7 @@ public async Task SummarizeAsync( this.isDisposed, this); + // Attempt to create a valid endpoint URL for the request. if (!TryCreateSummarizeRequestUri( out var requestUri)) { @@ -220,6 +231,7 @@ public async Task SummarizeAsync( $"Failed to create a valid URL for the request."); } + // Serialize the provided options and POST the request... var response = await this.client .PostAsJsonAsync( @@ -228,18 +240,19 @@ await this.client JsonSerializerOptions, cancellationToken); + // ...then process the response and return the result. return await ProcessResponseAsync( response, cancellationToken); } /// - /// + /// Sends an answer generation request to Kagi. /// - /// - /// - /// - /// + /// The options for generating the answer. + /// Token to observe while waiting for the task to complete. + /// A task that represents the asynchronous operation, containing the answer result. + /// Thrown if the request fails. public async Task AnswerAsync( KagiAnswerOptions options, CancellationToken cancellationToken = default) @@ -254,6 +267,7 @@ public async Task AnswerAsync( this.isDisposed, this); + // Attempt to create a valid endpoint URL for the request. if (!TryCreateAnswerRequestUri( out var requestUri)) { @@ -261,6 +275,7 @@ public async Task AnswerAsync( $"Failed to create a valid URL for the request."); } + // Serialize the provided options and POST the request... var response = await this.client .PostAsJsonAsync( @@ -269,19 +284,20 @@ await this.client JsonSerializerOptions, cancellationToken); + // ...then process the response and return the result. return await ProcessResponseAsync( response, cancellationToken); } /// - /// + /// Sends a search request to Kagi. /// - /// - /// - /// - /// - /// + /// The search query. + /// Limit for the number of results returned. + /// Token to observe while waiting for the task to complete. + /// A task that represents the asynchronous operation, containing the search result. + /// Thrown if the request fails. public async Task SearchAsync( string query, int limit, @@ -302,6 +318,7 @@ public async Task SearchAsync( this.isDisposed, this); + // Attempt to create a valid endpoint URL for the request. if (!TryCreateSearchRequestUri( query, limit, @@ -311,24 +328,26 @@ public async Task SearchAsync( $"Failed to create a valid URL for the request."); } + // GET the request... var response = await this.client .GetAsync( requestUri, cancellationToken); + // ...then process the response and return the result. return await ProcessResponseAsync( response, cancellationToken); } /// - /// + /// Sends a web enrichment search request to Kagi. /// - /// - /// - /// - /// + /// The search query. + /// Token to observe while waiting for the task to complete. + /// A task that represents the asynchronous operation, containing the search result. + /// Thrown if the request fails. public async Task SearchWebEnrichmentsAsync( string query, CancellationToken cancellationToken = default) @@ -343,6 +362,7 @@ public async Task SearchWebEnrichmentsAsync( this.isDisposed, this); + // Attempt to create a valid endpoint URL for the request. if (!TryCreateSearchWebEnrichmentsRequestUri( query, out var requestUri)) @@ -351,24 +371,26 @@ public async Task SearchWebEnrichmentsAsync( $"Failed to create a valid URL for the request."); } + // GET the request... var response = await this.client .GetAsync( requestUri, cancellationToken); + // ...then process the response and return the result. return await ProcessResponseAsync( response, cancellationToken); } /// - /// + /// Sends a news enrichment search request to Kagi. /// - /// - /// - /// - /// + /// The search query. + /// Token to observe while waiting for the task to complete. + /// A task that represents the asynchronous operation, containing the search result. + /// Thrown if the request fails. public async Task SearchNewsEnrichmentsAsync( string query, CancellationToken cancellationToken = default) @@ -383,6 +405,7 @@ public async Task SearchNewsEnrichmentsAsync( this.isDisposed, this); + // Attempt to create a valid endpoint URL for the request. if (!TryCreateSearchNewsEnrichmentsRequestUri( query, out var requestUri)) @@ -391,19 +414,21 @@ public async Task SearchNewsEnrichmentsAsync( $"Failed to create a valid URL for the request."); } + // GET the request... var response = await this.client .GetAsync( requestUri, cancellationToken); + // ...then process the response and return the result. return await ProcessResponseAsync( response, cancellationToken); } /// - /// + /// Releases the resources used by the instance. /// public void Dispose() { @@ -421,10 +446,10 @@ public void Dispose() } /// - /// + /// Tries to create a URI for the summarize request. /// - /// - /// + /// The resulting URI, if successful. + /// True if the URI was created successfully; otherwise, false. private bool TryCreateSummarizeRequestUri( out Uri result) => Uri.TryCreate( @@ -433,10 +458,10 @@ private bool TryCreateSummarizeRequestUri( out result); /// - /// + /// Tries to create a URI for the answer request. /// - /// - /// + /// The resulting URI, if successful. + /// True if the URI was created successfully; otherwise, false. private bool TryCreateAnswerRequestUri( out Uri result) => Uri.TryCreate( @@ -445,12 +470,12 @@ private bool TryCreateAnswerRequestUri( out result); /// - /// + /// Tries to create a URI for the search request. /// - /// - /// - /// - /// + /// The search query. + /// Limit for the number of results. + /// The resulting URI, if successful. + /// True if the URI was created successfully; otherwise, false. private bool TryCreateSearchRequestUri( string query, int limit, @@ -466,11 +491,11 @@ private bool TryCreateSearchRequestUri( out result); /// - /// + /// Tries to create a URI for the web enrichment search request. /// - /// - /// - /// + /// The search query. + /// The resulting URI, if successful. + /// True if the URI was created successfully; otherwise, false. private bool TryCreateSearchWebEnrichmentsRequestUri( string query, out Uri result) => @@ -484,11 +509,11 @@ private bool TryCreateSearchWebEnrichmentsRequestUri( out result); /// - /// + /// Tries to create a URI for the news enrichment search request. /// - /// - /// - /// + /// The search query. + /// The resulting URI, if successful. + /// True if the URI was created successfully; otherwise, false. private bool TryCreateSearchNewsEnrichmentsRequestUri( string query, out Uri result) => @@ -502,9 +527,9 @@ private bool TryCreateSearchNewsEnrichmentsRequestUri( out result); /// - /// + /// Releases the resources used by the instance. /// - /// + /// True if managed resources should be disposed; otherwise, false. private void Dispose( bool disposing) { @@ -516,7 +541,7 @@ private void Dispose( } /// - /// + /// Destroys the instance. /// ~KagiClient() { diff --git a/source/Kagi/KagiError.cs b/source/Kagi/KagiError.cs index 6ace14e..0f469ac 100644 --- a/source/Kagi/KagiError.cs +++ b/source/Kagi/KagiError.cs @@ -6,26 +6,26 @@ namespace Kagi { /// - /// + /// Represents an error that occured. /// public class KagiError { /// - /// + /// The for the error. /// [JsonPropertyName( "code")] public KagiErrorCode Code { get; init; } /// - /// + /// The message for the error. /// [JsonPropertyName( "msg")] public string Message { get; init; } /// - /// + /// The location reference for the error, if any. /// [JsonPropertyName( "ref")] diff --git a/source/Kagi/KagiErrorCode.cs b/source/Kagi/KagiErrorCode.cs index b66c9f6..8313745 100644 --- a/source/Kagi/KagiErrorCode.cs +++ b/source/Kagi/KagiErrorCode.cs @@ -6,7 +6,7 @@ namespace Kagi { /// - /// + /// Enumerates the possible error codes. /// [JsonConverter( typeof(JsonNumberEnumConverter))] diff --git a/source/Kagi/KagiErrorResult.cs b/source/Kagi/KagiErrorResult.cs index 9b6582d..d388174 100644 --- a/source/Kagi/KagiErrorResult.cs +++ b/source/Kagi/KagiErrorResult.cs @@ -8,13 +8,13 @@ namespace Kagi { /// - /// + /// Represents the result of an errored operation. /// public class KagiErrorResult : KagiResult { /// - /// + /// The collection of that occurred, if any. /// [JsonPropertyName( "error")] diff --git a/source/Kagi/KagiException.cs b/source/Kagi/KagiException.cs index 49ac94a..8187317 100644 --- a/source/Kagi/KagiException.cs +++ b/source/Kagi/KagiException.cs @@ -5,28 +5,24 @@ namespace Kagi { /// - /// + /// Represents an exception that wraps zero or more + /// for a given operation. /// public class KagiException : Exception { /// - /// + /// The collection of for the exception. /// public ImmutableArray Errors { get; init; } - /// - /// - /// + /// public KagiException() : this( default) { } - /// - /// - /// - /// + /// public KagiException( string message) : this( @@ -35,10 +31,11 @@ public KagiException( { } /// - /// + /// Initializes a new instance of the + /// class with a specified error message and collection of . /// - /// - /// + /// The message that describes the error. + /// A collection of for the exception. public KagiException( string message, ImmutableArray errors) : @@ -49,11 +46,13 @@ public KagiException( { } /// - /// + /// Initializes a new instance of the + /// class with a specified error message, collection of , + /// and a reference to the inner exception that is the cause of this exception. /// - /// - /// - /// + /// The message that describes the error. + /// A collection of for the exception. + /// The inner exception that is the cause of this exception. public KagiException( string message, ImmutableArray errors, diff --git a/source/Kagi/KagiRecordSearchData.cs b/source/Kagi/KagiRecordSearchData.cs index 96903da..3c0f8e3 100644 --- a/source/Kagi/KagiRecordSearchData.cs +++ b/source/Kagi/KagiRecordSearchData.cs @@ -5,42 +5,40 @@ namespace Kagi { - /// - /// - /// + /// public class KagiRecordSearchData : KagiSearchData { /// - /// + /// The URL for the search record. /// [JsonPropertyName( "url")] public Uri Url { get; init; } /// - /// + /// The title for the search record. /// [JsonPropertyName( "title")] public string Title { get; init; } /// - /// + /// The snippet for the search record, if any. /// [JsonPropertyName( "snippet")] public string Snippet { get; init; } /// - /// + /// The publication date for the search record, if any. /// [JsonPropertyName( "published")] public DateTime? PublicationDate { get; init; } /// - /// + /// The image associated with the search record, if any. /// [JsonPropertyName( "thumbnail")] diff --git a/source/Kagi/KagiRecordSearchDataThumbnail.cs b/source/Kagi/KagiRecordSearchDataThumbnail.cs index 6d3ac74..358e622 100644 --- a/source/Kagi/KagiRecordSearchDataThumbnail.cs +++ b/source/Kagi/KagiRecordSearchDataThumbnail.cs @@ -6,7 +6,7 @@ namespace Kagi { /// - /// + /// Represents an image associated with a search record. /// public class KagiRecordSearchDataThumbnail { @@ -19,8 +19,12 @@ public class KagiRecordSearchDataThumbnail private string UrlOrProxyPathFragment { get; init; } /// - /// + /// The image URL. /// + /// + /// Proxied image URLs are automatically fixed-up using + /// . + /// [JsonIgnore] public Uri Url => KagiUrlHelper.IsImageProxyPathFragment( @@ -31,14 +35,14 @@ public class KagiRecordSearchDataThumbnail UrlOrProxyPathFragment); /// - /// + /// The width of the image, if any. /// [JsonPropertyName( "width")] public int? Width { get; init; } /// - /// + /// The height of the image, if any. /// [JsonPropertyName( "height")] diff --git a/source/Kagi/KagiRelatedQuerySearchData.cs b/source/Kagi/KagiRelatedQuerySearchData.cs index 34ab97e..a2c1312 100644 --- a/source/Kagi/KagiRelatedQuerySearchData.cs +++ b/source/Kagi/KagiRelatedQuerySearchData.cs @@ -7,14 +7,12 @@ namespace Kagi { - /// - /// - /// + /// public class KagiRelatedQuerySearchData : KagiSearchData { /// - /// + /// A collection of related search queries. /// [JsonPropertyName( "list")] diff --git a/source/Kagi/KagiResult.cs b/source/Kagi/KagiResult.cs index c5c2207..ab5a34f 100644 --- a/source/Kagi/KagiResult.cs +++ b/source/Kagi/KagiResult.cs @@ -6,12 +6,12 @@ namespace Kagi { /// - /// + /// Represents the result of an operation. /// public class KagiResult { /// - /// + /// The request metadata for the result. /// [JsonPropertyName( "meta")] diff --git a/source/Kagi/KagiResultMetadata.cs b/source/Kagi/KagiResultMetadata.cs index 739fe9f..0c541db 100644 --- a/source/Kagi/KagiResultMetadata.cs +++ b/source/Kagi/KagiResultMetadata.cs @@ -6,33 +6,33 @@ namespace Kagi { /// - /// + /// Represents the result metadata for an operation. /// public class KagiResultMetadata { /// - /// + /// The request ID. /// [JsonPropertyName( "id")] public string RequestId { get; init; } /// - /// + /// The name of the server node that serviced the request. /// [JsonPropertyName( "node")] public string NodeName { get; init; } /// - /// + /// The duration the server took to service the request, in milliseconds. /// [JsonPropertyName( "ms")] public int DurationInMilliseconds { get; init; } /// - /// + /// The remaining API balance after the request was serviced, in U.S. dollars. /// [JsonPropertyName( "api_balance")] diff --git a/source/Kagi/KagiSearchData.cs b/source/Kagi/KagiSearchData.cs index 6687d00..c65d31c 100644 --- a/source/Kagi/KagiSearchData.cs +++ b/source/Kagi/KagiSearchData.cs @@ -6,8 +6,14 @@ namespace Kagi { /// - /// + /// Represents the response data for a + /// . /// + /// + /// Response data is polymorphic and should be either + /// or + /// . + /// [JsonPolymorphic( TypeDiscriminatorPropertyName = "t")] [JsonDerivedType( @@ -19,7 +25,7 @@ namespace Kagi public class KagiSearchData { /// - /// + /// The type for the search output. /// [JsonPropertyName( "t")] diff --git a/source/Kagi/KagiSearchDataType.cs b/source/Kagi/KagiSearchDataType.cs index 92162ca..a874352 100644 --- a/source/Kagi/KagiSearchDataType.cs +++ b/source/Kagi/KagiSearchDataType.cs @@ -6,19 +6,20 @@ namespace Kagi { /// - /// + /// Enumerates the types of response data for a + /// . /// [JsonConverter( typeof(JsonNumberEnumConverter))] public enum KagiSearchDataType { /// - /// + /// A search result. /// Record = 0, /// - /// + /// A collection of related search queries. /// RelatedQuery = 1, } diff --git a/source/Kagi/KagiSearchResult.cs b/source/Kagi/KagiSearchResult.cs index af42c27..9d2c067 100644 --- a/source/Kagi/KagiSearchResult.cs +++ b/source/Kagi/KagiSearchResult.cs @@ -8,13 +8,13 @@ namespace Kagi { /// - /// + /// Represents the result of a search operation. /// public class KagiSearchResult : KagiResult { /// - /// + /// The response data for the result. /// [JsonPropertyName( "data")] diff --git a/source/Kagi/KagiSummarizeData.cs b/source/Kagi/KagiSummarizeData.cs index 85cd563..23664b8 100644 --- a/source/Kagi/KagiSummarizeData.cs +++ b/source/Kagi/KagiSummarizeData.cs @@ -6,19 +6,20 @@ namespace Kagi { /// - /// + /// Represents the response data for a + /// . /// public class KagiSummarizeData { /// - /// + /// The summarize output. /// [JsonPropertyName( "output")] public string Output { get; init; } /// - /// + /// The number of tokens processed to produce the summarize output. /// [JsonPropertyName( "tokens")] diff --git a/source/Kagi/KagiSummarizeOptions.cs b/source/Kagi/KagiSummarizeOptions.cs index 4cf27b7..e9e7b22 100644 --- a/source/Kagi/KagiSummarizeOptions.cs +++ b/source/Kagi/KagiSummarizeOptions.cs @@ -6,47 +6,59 @@ namespace Kagi { /// - /// + /// Represents the options for a summarize operation. /// public class KagiSummarizeOptions { /// - /// + /// The URL of the document to summarize. /// + /// + /// Exclusive with . + /// [JsonPropertyName( "url")] public Uri Url { get; init; } /// - /// + /// The text to summarize. /// + /// + /// Exclusive with . + /// [JsonPropertyName( "text")] public string Text { get; init; } /// - /// + /// The to use. /// [JsonPropertyName( "engine")] public KagiSummaryEngine Engine { get; init; } /// - /// + /// The to output. /// [JsonPropertyName( "summary_type")] public KagiSummaryKind Kind { get; init; } /// - /// + /// The to output. /// + /// + /// If no language is specified, the language of the document/text provided + /// is allowed to influence the summarizer's output. Specifying a language + /// will add an explicit translation step, to translate the summary to the + /// desired language. + /// [JsonPropertyName( "target_language")] public KagiSummaryLanguage OutputLanguage { get; init; } /// - /// + /// Whether to allow cached requests and responses. /// [JsonPropertyName( "cache")] diff --git a/source/Kagi/KagiSummarizeResult.cs b/source/Kagi/KagiSummarizeResult.cs index d57e229..f412c9b 100644 --- a/source/Kagi/KagiSummarizeResult.cs +++ b/source/Kagi/KagiSummarizeResult.cs @@ -6,13 +6,13 @@ namespace Kagi { /// - /// + /// Represents the result of a summarize operation. /// public class KagiSummarizeResult : KagiResult { /// - /// + /// The response data for the result. /// [JsonPropertyName( "data")] diff --git a/source/Kagi/KagiSummaryEngine.cs b/source/Kagi/KagiSummaryEngine.cs index 7ab71e2..f45ffc9 100644 --- a/source/Kagi/KagiSummaryEngine.cs +++ b/source/Kagi/KagiSummaryEngine.cs @@ -11,28 +11,28 @@ namespace Kagi { /// - /// + /// Enumerates the provided summarization engines. /// [JsonConverter( typeof(JsonEnumMemberEnumConverter))] public enum KagiSummaryEngine { /// - /// + /// Provides a friendly, descriptive, fast summary. /// [EnumMember( Value = "cecil")] Cecil, /// - /// + /// Provides a formal, technical, analytical summary. /// [EnumMember( Value = "agnes")] Agnes, /// - /// + /// Provides a best-in-class summary using Kagi's enterprise-grade model. /// [EnumMember( Value = "muriel")] diff --git a/source/Kagi/KagiSummaryKind.cs b/source/Kagi/KagiSummaryKind.cs index 575f6ac..00d2091 100644 --- a/source/Kagi/KagiSummaryKind.cs +++ b/source/Kagi/KagiSummaryKind.cs @@ -11,21 +11,21 @@ namespace Kagi { /// - /// + /// Enumerates the different kinds of summarization. /// [JsonConverter( typeof(JsonEnumMemberEnumConverter))] public enum KagiSummaryKind { /// - /// + /// A paragraph or more of summary prose. /// [EnumMember( Value = "summary")] Summary, /// - /// + /// A bulleted list of key points. /// [EnumMember( Value = "takeaway")] diff --git a/source/Kagi/KagiSummaryLanguage.cs b/source/Kagi/KagiSummaryLanguage.cs index 3fc6935..4f3385f 100644 --- a/source/Kagi/KagiSummaryLanguage.cs +++ b/source/Kagi/KagiSummaryLanguage.cs @@ -11,217 +11,217 @@ namespace Kagi { /// - /// + /// Enumerates the supported output languages for summarization. /// [JsonConverter( typeof(JsonEnumMemberEnumConverter))] public enum KagiSummaryLanguage { /// - /// + /// The Bulgarian language. /// [EnumMember( Value = "BG")] Bulgarian, /// - /// + /// The Czech language. /// [EnumMember( Value = "CS")] Czech, /// - /// + /// The Danish language. /// [EnumMember( Value = "DA")] Danish, /// - /// + /// The German language. /// [EnumMember( Value = "DE")] German, /// - /// + /// The Greek language. /// [EnumMember( Value = "EL")] Greek, /// - /// + /// The English language. /// [EnumMember( Value = "EN")] English, /// - /// + /// The Spanish language. /// [EnumMember( Value = "ES")] Spanish, /// - /// + /// The Estonian language. /// [EnumMember( Value = "ET")] Estonian, /// - /// + /// The Finnish language. /// [EnumMember( Value = "FI")] Finnish, /// - /// + /// The French language. /// [EnumMember( Value = "FR")] French, /// - /// + /// The Hungarian language. /// [EnumMember( Value = "HU")] Hungarian, /// - /// + /// The Indonesian language. /// [EnumMember( Value = "ID")] Indonesian, /// - /// + /// The Italian language. /// [EnumMember( Value = "IT")] Italian, /// - /// + /// The Japanese language. /// [EnumMember( Value = "JA")] Japanese, /// - /// + /// The Korean language. /// [EnumMember( Value = "KO")] Korean, /// - /// + /// The Lithuanian language. /// [EnumMember( Value = "LT")] Lithuanian, /// - /// + /// The Latvian language. /// [EnumMember( Value = "LV")] Latvian, /// - /// + /// The Norwegian language. /// [EnumMember( Value = "NB")] Norwegian, /// - /// + /// The Dutch language. /// [EnumMember( Value = "NL")] Dutch, /// - /// + /// The Polish language. /// [EnumMember( Value = "PL")] Polish, /// - /// + /// The Portuguese language. /// [EnumMember( Value = "PT")] Portuguese, /// - /// + /// The Romanian language. /// [EnumMember( Value = "RO")] Romanian, /// - /// + /// The Russian language. /// [EnumMember( Value = "RU")] Russian, /// - /// + /// The Slovak language. /// [EnumMember( Value = "SK")] Slovak, /// - /// + /// The Slovenian language. /// [EnumMember( Value = "SL")] Slovenian, /// - /// + /// The Swedish language. /// [EnumMember( Value = "SV")] Swedish, /// - /// + /// The Turkish language. /// [EnumMember( Value = "TR")] Turkish, /// - /// + /// The Ukrainian language. /// [EnumMember( Value = "UK")] Ukrainian, /// - /// + /// The Chinese (simplified) language. /// [EnumMember( Value = "ZH")] ChineseSimplified, /// - /// + /// The Chinese (traditional) language. /// [EnumMember( Value = "ZH-HANT")] diff --git a/source/Kagi/KagiUrlHelper.cs b/source/Kagi/KagiUrlHelper.cs index da108a5..90cbe55 100644 --- a/source/Kagi/KagiUrlHelper.cs +++ b/source/Kagi/KagiUrlHelper.cs @@ -3,33 +3,39 @@ namespace Kagi { /// - /// + /// Provides -related helper functionality. /// public static class KagiUrlHelper { /// - /// + /// The prefix that proxied image URL path fragments start with. /// private const string ImageProxyPathFragment = "/proxy"; /// - /// + /// The proxy image base URL i.e. what a proxied image URL + /// path fragment requires to be a complete URL. /// private const string ImageProxyBaseUrlValue = "https://kagi.com/"; /// - /// + /// Gets the proxy image base URL i.e. what a proxied image URL + /// path fragment requires to be a complete URL. /// public static Uri ImageProxyBaseUrl { get; } = new Uri(ImageProxyBaseUrlValue); /// - /// + /// Returns whether the specified path fragment is an image proxy URL path fragment. /// - /// + /// The path fragment specified. /// + /// + /// Used internally when fixing-up . + /// You will probably have no use for this method. + /// public static bool IsImageProxyPathFragment( string value) { @@ -44,11 +50,17 @@ public static bool IsImageProxyPathFragment( } /// - /// + /// Returns a complete image proxy URL for the specified image proxy URL path fragment. /// - /// + /// The image proxy URL path fragment specified. /// - /// + /// + /// Thrown when a image proxy URL cannot be created. + /// + /// + /// Used internally when fixing-up . + /// You will probably have no use for this method. + /// public static Uri ToImageProxyUrl( string value) {