Added comments in templates for public members to address CS1591 warn…

…ings
CharlieDigital · Sep 20, 2024 · 4e8873b · 4e8873b
1 parent e245af8
commit 4e8873b
Show file tree

Hide file tree

Showing 4 changed files with 69 additions and 4 deletions.
diff --git a/generator/PromptGenerator.cs b/generator/PromptGenerator.cs
@@ -49,14 +49,26 @@ public void Execute(GeneratorExecutionContext context)
 
         namespace {{prompt.Namespace}};
 
+        /// <summary>
+        /// Generated prompt for `{{prompt.Name}}`
+        /// </summary>
         public partial class {{prompt.Name}}Prompt(
           {{parameters}}
         ) : {{prompt.BaseClass}}
         {
+          /// <summary>
+          /// The base prompt template string for `{{prompt.Name}}`
+          /// </summary>
           public override string Text => $$"""
         {{tmpl}}
         """;
 
+          /// <summary>
+          /// Settings for the prompt `{{prompt.Name}}`:
+          ///   MaxTokens = {{prompt.MaxTokens}}
+          ///   Temperature = {{prompt.Temperature}}d
+          ///   TopP = {{prompt.TopP}}d
+          /// </summary>
           public override OpenAIPromptExecutionSettings Settings => new OpenAIPromptExecutionSettings
           {
             MaxTokens = {{prompt.MaxTokens}},

diff --git a/generator/PromptTemplateAttribute.cs b/generator/PromptTemplateAttribute.cs
@@ -34,6 +34,14 @@ internal static class PromptTemplateAttributeSource
 
     namespace SKPromptGenerator;
 
+    /// <summary>
+    /// Attribute applied to `const string` class fields to generate a prompt class.
+    /// Use this when specifying a custom base class for executing the prompt.
+    /// </summary>
+    /// <param name="maxTokens">The maximum number of tokens; default is 500</param>
+    /// <param name="temperature">The temperature; default is 0.5</param>
+    /// <param name="topP">The Top P parameter; default is 0</param>
+    /// <typeparam name="T">The base type for the template inheriting from `PromptTemplateBase`</typeparam>
     [AttributeUsage(AttributeTargets.Field | AttributeTargets.Property, Inherited = false, AllowMultiple = false)]
     public class PromptTemplateAttribute<T>(
       int maxTokens = 500,
@@ -45,6 +53,13 @@ public class PromptTemplateAttribute<T>(
       public double TopP => topP;
     }
 
+    /// <summary>
+    /// Attribute applied to `const string` class fields to generate a prompt class.
+    /// </summary>
+    /// <param name="maxTokens">The maximum number of tokens; default is 500</param>
+    /// <param name="temperature">The temperature; default is 0.5</param>
+    /// <param name="topP">The Top P parameter; default is 0</param>
+    /// <typeparam name="T">The base type for the template inheriting from `PromptTemplateBase`</typeparam>
     [AttributeUsage(AttributeTargets.Field | AttributeTargets.Property, Inherited = false, AllowMultiple = false)]
     public class PromptTemplateAttribute(
       int maxTokens = 500,

diff --git a/generator/PromptTemplateBase.cs b/generator/PromptTemplateBase.cs
@@ -37,16 +37,34 @@ internal static class PromptTemplateBaseSource
 
     namespace SKPromptGenerator;
 
+    /// <summary>
+    /// Abstract base class for executing the prompt.  Override this class to
+    /// provide custom execution of the prompt.
+    /// </summary>
     public abstract class PromptTemplateBase
     {
-      private static readonly JsonSerializerOptions SerializerOptions = new() {
+      protected static readonly JsonSerializerOptions SerializerOptions = new() {
         PropertyNameCaseInsensitive = true
       };
 
+      /// <summary>
+      /// The execution settings for this prompt.
+      /// </summary>
       public abstract OpenAIPromptExecutionSettings Settings { get; }
 
+      /// <summary>
+      /// The text of this prompt.
+      /// </summary>
       public abstract string Text { get; }
 
+      /// <summary>
+      /// Executes the prompt using the default execution.  Override this method
+      /// to provide custom execution logic (e.g. logging, telemetry, etc.)
+      /// </summary>
+      /// <param name="kernel">The Semantic Kernel instance.</param>
+      /// <param name="serviceId">An optional service ID to specify for execution.</param>
+      /// <param name="cancellation">An optional cancellation token.</param>
+      /// <returns>A string with the results of execution.</returns>
       public virtual async Task<string> ExecuteAsync(
         Kernel kernel,
         #nullable enable
@@ -66,6 +84,15 @@ public virtual async Task<string> ExecuteAsync(
         return result.ToString();
       }
 
+      /// <summary>
+      /// Executes the prompt and expects a JSON response that will be deserialized
+      /// to the type `T`.
+      /// </summary>
+      /// <param name="kernel">The Semantic Kernel instance.</param>
+      /// <param name="serviceId">An optional service ID to specify for execution.</param>
+      /// <param name="cancellation">An optional cancellation token.</param>
+      /// <typeparam name="T">The type `T` of the response object.</typeparam>
+      /// <returns>An instance of type `T` deserialized from the JSON response.</returns>
       #nullable enable
       public virtual async Task<T?> ExecuteAsync<T>(
         Kernel kernel,
@@ -78,6 +105,17 @@ public virtual async Task<string> ExecuteAsync(
       }
       #nullable disable
 
+      /// <summary>
+      /// Executes the prompt and expects a JSON response that will be deserialized
+      /// to the type `T`.  This call includes the JSON result as part of the tuple.
+      /// This method call will perform trimming of JSON fences if present using
+      /// regular string find/replace.
+      /// </summary>
+      /// <param name="kernel">The Semantic Kernel instance.</param>
+      /// <param name="serviceId">An optional service ID to specify for execution.</param>
+      /// <param name="cancellation">An optional cancellation token.</param>
+      /// <typeparam name="T">The type `T` of the response object.</typeparam>
+      /// <returns>An instance of type `T` deserialized from the JSON response in a tuple with the full JSON response as well..</returns>
       #nullable enable
       public virtual async Task<(T? Result, string Json)> ExecuteWithJsonAsync<T>(
         Kernel kernel,

diff --git a/generator/SKPromptGenerator.csproj b/generator/SKPromptGenerator.csproj
@@ -24,9 +24,9 @@
     <PackageReleaseNotes>https://github.com/CharlieDigital/SKPromptGenerator/releases</PackageReleaseNotes>
     <RepositoryType>git</RepositoryType>
     <SignAssembly>False</SignAssembly>
-    <AssemblyVersion>0.4.4</AssemblyVersion>
-    <FileVersion>0.4.4</FileVersion>
-    <Version>0.4.4</Version>
+    <AssemblyVersion>0.4.5</AssemblyVersion>
+    <FileVersion>0.4.5</FileVersion>
+    <Version>0.4.5</Version>
     <NeutralLanguage>en</NeutralLanguage>
     <DevelopmentDependency>true</DevelopmentDependency>
     <SuppressDependenciesWhenPacking>true</SuppressDependenciesWhenPacking>