more KDocs

Author: ianbotsf

aws-runtime/aws-config/common/src/aws/sdk/kotlin/runtime/region/ValidateRegion.kt

@@ -20,9 +20,56 @@ private object Rfc3986CharSets {
     val regName = unreserved + pctEncoded + subDelims
 }
 
+/**
+ * Determines if the given region is valid for the purposes of endpoint lookup, specifically that the region is suitable
+ * to use in a URI hostname according to [RFC 3986 § 3.2.2](https://www.rfc-editor.org/rfc/rfc3986#section-3.2.2).
+ *
+ * Valid characters for regions include:
+ * * URI unreserved characters:
+ *   * Uppercase letters (`A` through `Z`)
+ *   * Lowercase letters (`a` through `z`)
+ *   * Digits (`0` through `9`)
+ *   * Hyphen (`-`)
+ *   * Period/dot (`.`)
+ *   * Tilde (`~`)
+ *   * Underscore (`_`)
+ * * Percent (`%`)
+ * * URI sub-delimiters
+ *   * Ampersand (`&`)
+ *   * Apostrophe (`'`)
+ *   * Asterisk (`*`)
+ *   * Comma (`,`)
+ *   * Dollar sign (`$`)
+ *   * Equals sign (`=`)
+ *   * Exclamation point (`!`)
+ *   * Parentheses (`(` and `)`)
+ *   * Plus (`+`)
+ *   * Semicolon (`;`)
+ *
+ * Notable characters which are _invalid_ for regions include:
+ * * Space (` `)
+ * * At sign (`@`)
+ * * Backtick/grave (`` ` ``)
+ * * Braces (`{` and `}`)
+ * * Brackets (`[` and `]`)
+ * * Caret (`^`)
+ * * Colon (`:`)
+ * * Double quote (`"`)
+ * * Hash/number sign (`#`)
+ * * Inequality signs (`<` and `>`)
+ * * Pipe (`|`)
+ * * Question mark (`?`)
+ * * Slashes (`/` and `\`)
+ * * All non-ASCII characters (e.g., Unicode characters)
+ */
 @InternalSdkApi
 public fun isRegionValid(region: String): Boolean = region.isNotEmpty() && region.all(Rfc3986CharSets.regName::contains)
 
+/**
+ * Validates that a region is suitable to use in a URI hostname according to
+ * [RFC 3986 § 3.2.2](https://www.rfc-editor.org/rfc/rfc3986#section-3.2.2). See [isRegionValid] for a detailed
+ * description of the validation criteria.
+ */
 @InternalSdkApi
 public fun validateRegion(region: String): String = region.also {
     if (!isRegionValid(region)) {