Add documentation

CodegenBot/CaretRef.cs

@@ -29,6 +29,22 @@ public class CaretRef
     /// </summary>
     public IReadOnlyList<CaretTag>? Tags { get; init; }
 
+    /// <summary>
+    /// Creates a new caret ref. This can be embedded into a string that you pass to Codegen Bot  via GraphQLClient.AddText,
+    /// GraphQLClient.AddTextByTags, GraphQLClient.AddFile, etc. When you do that, it creates a caret that your bot and
+    /// other bots can insert text into. 
+    /// </summary>
+    /// <param name="id">The ID of the caret. Each caret has a unique ID. The main purpose of this ID is so that you can
+    /// insert text into that specific caret later without having to specify tags.</param>
+    /// <param name="separator">Whenever text is inserted into this caret, it is separated by this value. By default it's empty
+    /// which means no separators are used. A common example might be using the string ", " as a separator for comma-separated
+    /// stuff like arguments for a function call.</param>
+    /// <param name="indentation">The amount of indentation to add to every line of text inserted at this caret. Note that
+    /// this doesn't affect the first line of text inserted at this caret; Codegen Bot assumes that the first line has the
+    /// correct amount of indentation. By default this is empty, which means no indentation will be added. There is no way
+    /// to use this parameter to remove indentation from inserted text.</param>
+    /// <returns>The CaretRef object, which can have .ToString() called on it to serialize it into a format that Codegen
+    /// Bot will recognize.</returns>
     public static CaretRef New(string id, string separator = "", string indentation = "")
     {
         return new CaretRef()
@@ -39,6 +55,21 @@ public static CaretRef New(string id, string separator = "", string indentation
         };
     }
 
+    /// <summary>
+    /// Creates a new caret ref. This can be embedded into a string that you pass to Codegen Bot  via GraphQLClient.AddText,
+    /// GraphQLClient.AddTextByTags, GraphQLClient.AddFile, etc. When you do that, it creates a caret that your bot and
+    /// other bots can insert text into.
+    /// 
+    /// This overload auto-generates the caret's ID. 
+    /// </summary>
+    /// <param name="separator">Whenever text is inserted into this caret, it is separated by this value. By default it's empty
+    /// which means no separators are used. A common example might be using the string ", " as a separator for comma-separated
+    /// stuff like arguments for a function call.</param>
+    /// <param name="tags">The metadata for this caret. This metadata can be used by your bot or other bots to insert text
+    /// in one or more carets that have metadata that matches whatever is specified to GraphQLClient.AddTextByTags or
+    /// GraphQLClient.AddKeyedTextByTags.</param>
+    /// <returns>The CaretRef object, which can have .ToString() called on it to serialize it into a format that Codegen
+    /// Bot will recognize.</returns>
     public static CaretRef New(out CaretRef caretRef, string separator, params CaretTag[] tags)
     {
         caretRef = new CaretRef()
@@ -51,6 +82,25 @@ public static CaretRef New(out CaretRef caretRef, string separator, params Caret
         return caretRef;
     }
 
+    /// <summary>
+    /// Creates a new caret ref. This can be embedded into a string that you pass to Codegen Bot  via GraphQLClient.AddText,
+    /// GraphQLClient.AddTextByTags, GraphQLClient.AddFile, etc. When you do that, it creates a caret that your bot and
+    /// other bots can insert text into.
+    ///
+    /// This overload auto-generates the caret's ID.
+    /// </summary>
+    /// <param name="separator">Whenever text is inserted into this caret, it is separated by this value. By default it's empty
+    /// which means no separators are used. A common example might be using the string ", " as a separator for comma-separated
+    /// stuff like arguments for a function call.</param>
+    /// <param name="indentation">The amount of indentation to add to every line of text inserted at this caret. Note that
+    /// this doesn't affect the first line of text inserted at this caret; Codegen Bot assumes that the first line has the
+    /// correct amount of indentation. By default this is empty, which means no indentation will be added. There is no way
+    /// to use this parameter to remove indentation from inserted text.</param>
+    /// <param name="tags">The metadata for this caret. This metadata can be used by your bot or other bots to insert text
+    /// in one or more carets that have metadata that matches whatever is specified to GraphQLClient.AddTextByTags or
+    /// GraphQLClient.AddKeyedTextByTags.</param>
+    /// <returns>The CaretRef object, which can have .ToString() called on it to serialize it into a format that Codegen
+    /// Bot will recognize.</returns>
     public static CaretRef New(out CaretRef caretRef, string separator, string indentation, params CaretTag[] tags)
     {
         caretRef = new CaretRef()
@@ -63,6 +113,18 @@ public static CaretRef New(out CaretRef caretRef, string separator, string inden
         return caretRef;
     }
 
+    /// <summary>
+    /// Creates a new caret ref. This can be embedded into a string that you pass to Codegen Bot  via GraphQLClient.AddText,
+    /// GraphQLClient.AddTextByTags, GraphQLClient.AddFile, etc. When you do that, it creates a caret that your bot and
+    /// other bots can insert text into.
+    ///
+    /// This overload auto-generates the caret's ID. 
+    /// </summary>
+    /// <param name="tags">The metadata for this caret. This metadata can be used by your bot or other bots to insert text
+    /// in one or more carets that have metadata that matches whatever is specified to GraphQLClient.AddTextByTags or
+    /// GraphQLClient.AddKeyedTextByTags.</param>
+    /// <returns>The CaretRef object, which can have .ToString() called on it to serialize it into a format that Codegen
+    /// Bot will recognize.</returns>
     public static CaretRef New(out CaretRef caretRef, params CaretTag[] tags)
     {
         caretRef = new CaretRef()
@@ -75,6 +137,21 @@ public static CaretRef New(out CaretRef caretRef, params CaretTag[] tags)
         return caretRef;
     }
 
+    /// <summary>
+    /// Creates a new caret ref. This can be embedded into a string that you pass to Codegen Bot  via GraphQLClient.AddText,
+    /// GraphQLClient.AddTextByTags, GraphQLClient.AddFile, etc. When you do that, it creates a caret that your bot and
+    /// other bots can insert text into.
+    ///
+    /// This overload auto-generates the caret's ID. 
+    /// </summary>
+    /// <param name="separator">Whenever text is inserted into this caret, it is separated by this value. By default it's empty
+    /// which means no separators are used. A common example might be using the string ", " as a separator for comma-separated
+    /// stuff like arguments for a function call.</param>
+    /// <param name="tags">The metadata for this caret. This metadata can be used by your bot or other bots to insert text
+    /// in one or more carets that have metadata that matches whatever is specified to GraphQLClient.AddTextByTags or
+    /// GraphQLClient.AddKeyedTextByTags.</param>
+    /// <returns>The CaretRef object, which can have .ToString() called on it to serialize it into a format that Codegen
+    /// Bot will recognize.</returns>
     public static CaretRef New(string separator, params CaretTag[] tags)
     {
         var caretRef = new CaretRef()
@@ -87,6 +164,18 @@ public static CaretRef New(string separator, params CaretTag[] tags)
         return caretRef;
     }
 
+    /// <summary>
+    /// Creates a new caret ref. This can be embedded into a string that you pass to Codegen Bot  via GraphQLClient.AddText,
+    /// GraphQLClient.AddTextByTags, GraphQLClient.AddFile, etc. When you do that, it creates a caret that your bot and
+    /// other bots can insert text into.
+    ///
+    /// This overload auto-generates the caret's ID. 
+    /// </summary>
+    /// <param name="tags">The metadata for this caret. This metadata can be used by your bot or other bots to insert text
+    /// in one or more carets that have metadata that matches whatever is specified to GraphQLClient.AddTextByTags or
+    /// GraphQLClient.AddKeyedTextByTags.</param>
+    /// <returns>The CaretRef object, which can have .ToString() called on it to serialize it into a format that Codegen
+    /// Bot will recognize.</returns>
     public static CaretRef New(params CaretTag[] tags)
     {
         var caretRef = new CaretRef()
@@ -99,11 +188,24 @@ public static CaretRef New(params CaretTag[] tags)
         return caretRef;
     }
 
+    /// <summary>
+    /// Parses a string 
+    /// </summary>
+    /// <param name="str"></param>
+    /// <returns></returns>
     public static CaretRef? TryParse(string str)
     {
         return JsonSerializer.Deserialize(str, CaretRefJsonSerializer.Default.CaretRef);
     }
-
+
+    /// <summary>
+    /// Converts the caret to a string in a format that Codegen Bot recognizes.
+    /// The format is like this:
+    /// <<<<<<<<<{json}>>>>>>>>>
+    ///
+    /// The JSON string is an object that contains the properties of the caret (ID, separator, indentation, tags, etc.).
+    /// </summary>
+    /// <returns>The string representation of this caret</returns>
     public override string ToString()
     {
         var json = JsonSerializer.Serialize(this, CaretRefJsonSerializer.Default.CaretRef);