Updating the documentations of the tag helper classes.

Author: jooni91

docs/Griesoft.AspNetCore.ReCaptcha.xml

@@ -10,7 +10,8 @@
 namespace Griesoft.AspNetCore.ReCaptcha.TagHelpers
 {
     /// <summary>
-    /// Add a invisible reCAPTCHA div element to your page. Or add a 're-invisible' attribute to a button element to bind the invisible captcha to a button.
+    /// Add a invisible reCAPTCHA div element to your page. You may also use it by adding a 're-invisible' attribute to a button 
+    /// element which will automatically bind the challenge to it.
     /// </summary>
     /// <remarks>
     /// The <see cref="FormId"/> is required. With the exception that you set a <see cref="Callback"/> instead.
@@ -22,6 +23,17 @@ namespace Griesoft.AspNetCore.ReCaptcha.TagHelpers
     /// If the tag is not inside the form that is going to be submitted, you should use a custom callback function. The default callback function
     /// does not add the reCAPTCHA token to the form, which will result in response verification failure.
     /// </remarks>
+    /// <example>
+    /// The simplest use of the tag would be:
+    /// <code>
+    /// <button re-invisible formid="myForm">Submit</button>
+    /// </code>
+    /// 
+    /// Which will translate into the following HTML:
+    /// <code>
+    /// <button class="g-recaptcha" data-sitekey="your_site_key" data-callback="submitmyForm" data-badge="bottomleft">Submit</button>
+    /// </code>
+    /// </example>
     [HtmlTargetElement("recaptcha-invisible", Attributes = "callback", TagStructure = TagStructure.WithoutEndTag)]
     [HtmlTargetElement("recaptcha-invisible", Attributes = "formid", TagStructure = TagStructure.WithoutEndTag)]
     [HtmlTargetElement("button", Attributes = "re-invisible,callback")]
@@ -66,12 +78,13 @@ public RecaptchaInvisibleTagHelper(IOptionsMonitor<RecaptchaSettings> settings,
 
         /// <summary>
         /// The id of the form that will be submitted after a successful reCAPTCHA challenge. 
-        /// This does only apply when not specifying a custom <see cref="Callback"/>.
         /// </summary>
+        /// <remarks>This does only apply when not specifying a <see cref="Callback"/>.</remarks>
         public string? FormId { get; set; }
 
         /// <summary>
-        /// Set the name of your callback function, executed when the user submits a successful response. The "g-recaptcha-response" token is passed to your callback.
+        /// Set the name of your callback function, which is called when the reCAPTCHA challenge was successful. 
+        /// A "g-recaptcha-response" token is added to your callback function parameters for server-side verification.
         /// </summary>
         public string Callback { get; set; } = string.Empty;
 

src/ReCaptcha/TagHelpers/RecaptchaInvisibleTagHelper.cs

@@ -8,10 +8,11 @@
 namespace Griesoft.AspNetCore.ReCaptcha.TagHelpers
 {
     /// <summary>
-    /// Adds a script tag, which will load the required reCAPTCHA JavaScript API. Can be added
-    /// anywhere on your HTML page, but if you use a onload callback function you must place this
-    /// after that callback to avoid race conditions.
+    /// Adds a script tag, which will load the required reCAPTCHA API.
     /// </summary>
+    /// <remarks>
+    /// In case that you use an onload callback function you must place this tag after the callback script, to avoid race conditions.
+    /// </remarks>
     [HtmlTargetElement("recaptcha-script", TagStructure = TagStructure.WithoutEndTag)]
     public class RecaptchaScriptTagHelper : TagHelper
     {

src/ReCaptcha/TagHelpers/RecaptchaScriptTagHelper.cs

@@ -8,8 +8,24 @@
 namespace Griesoft.AspNetCore.ReCaptcha.TagHelpers
 {
     /// <summary>
-    /// A tag helper which adds a Google reCAPTCHA div element to your page.
+    /// A tag helper which adds a Google reCAPTCHA check box to your page.
     /// </summary>
+    /// <remarks>
+    /// If the reCAPTCHA element is outside of the form, the response token is not included in your form which will result in response verification failure.
+    /// This can be prevented by either placing the reCAPTCHA inside your form or by using a callback function which will add the token to your form after the
+    /// challenge was successfully completed.
+    /// </remarks>
+    ///  <example>
+    /// The simplest use of the tag would be:
+    /// <code>
+    /// <recaptcha />
+    /// </code>
+    /// 
+    /// Which will translate into the following HTML:
+    /// <code>
+    /// <div class="g-recaptcha" data-sitekey="your_site_key" data-size="normal" data-theme="light"></div>
+    /// </code>
+    /// </example>
     public class RecaptchaTagHelper : TagHelper
     {
         private readonly RecaptchaSettings _settings;