address PR feedback: add/cleanup KDocs, remove unnecessary debug logging, add runtime check for acceptable partition key value types, remove unused function, re-add accidentally-removed trailing comma from codegen

Author: ianbotsf

hll/dynamodb-mapper/dynamodb-mapper-ops-codegen/src/main/kotlin/aws/sdk/kotlin/hll/dynamodbmapper/codegen/operations/rendering/OperationRenderer.kt

@@ -96,7 +96,7 @@ internal class OperationRenderer(
 
         openBlock("private fun <T> #T.convert(", operation.request.type)
         requestMembers(MemberCodegenBehavior.Hoist) { write("#L: #T, ", name, type) }
-        write("schema: #T", MapperTypes.Items.itemSchema("T"))
+        write("schema: #T,", MapperTypes.Items.itemSchema("T"))
         closeAndOpenBlock(") = #L {", operation.request.lowLevelName)
         requestMembers(MemberCodegenBehavior.PassThrough) { write("#L = this@convert.#L", name, highLevel.name) }
         requestMembers(MemberCodegenBehavior.MapKeys) {
@@ -200,14 +200,5 @@ private inline operator fun Map<MemberCodegenBehavior, List<Member>>.invoke(
     }
 }
 
-private inline operator fun Map<MemberCodegenBehavior, List<Member>>.invoke(
-    predicate: (MemberCodegenBehavior) -> Boolean,
-    block: Member.() -> Unit,
-) {
-    entries.forEach { (behavior, members) ->
-        if (predicate(behavior)) members.forEach(block)
-    }
-}
-
 private val Structure.lowLevelName: String
     get() = "LowLevel${type.shortName}"

hll/dynamodb-mapper/dynamodb-mapper/common/src/aws/sdk/kotlin/hll/dynamodbmapper/expressions/Expressions.kt

@@ -29,4 +29,9 @@ public sealed interface Expression {
  */
 public sealed interface BooleanExpr : Expression
 
+/**
+ * A subtype of [Expression] that represents a key condition on a sort key, such as would be used for specifying a Query
+ * key. This is a [marker interface](https://en.wikipedia.org/wiki/Marker_interface_pattern) which adds no additional
+ * declarations.
+ */
 public sealed interface SortKeyExpr : Expression

hll/dynamodb-mapper/dynamodb-mapper/common/src/aws/sdk/kotlin/hll/dynamodbmapper/expressions/Filter.kt

@@ -661,7 +661,7 @@ public interface Filter {
     public fun AttributePath.isBetween(min: Expression, max: Expression): BooleanExpr
 
     /**
-     * Creates a range expression for verifying the sort key is between two other expressions
+     * Creates a range expression for verifying this expression is between two other expressions
      * @param min The lower bound value
      * @param max The upper bound value (inclusive)
      */

hll/dynamodb-mapper/dynamodb-mapper/common/src/aws/sdk/kotlin/hll/dynamodbmapper/expressions/SortKeyFilter.kt

@@ -20,7 +20,7 @@ public interface SortKey
  * { sortKey eq 42 }
  * ```
  *
- * This example creates an expression which checks whether an attribute named `foo` is equal to the value `42`.
+ * This example creates an expression which checks whether the sort key is equal to the value `42`.
  *
  * ## (Non-)Relationship to schema
  *
@@ -34,12 +34,12 @@ public interface SortKey
  *
  * A very common filter condition is verifying whether the value of the sort key is equal (or unequal) to another a
  * literal value. These comparisons are available by using the following functions:
- * * [eq] — checks if two values are equal (equivalent to Kotlin's `==` operator)
- * * [neq] — checks if two values are _not_ equal (equivalent to Kotlin's `!=` operator)
- * * [lt] — checks if a value is less than another value (equivalent to Kotlin's `<` operator)
- * * [lte] — checks if a value is less than _or equal to_ another value (equivalent to Kotlin's `<=` operator)
- * * [gt] — checks if a value is greater than another value (equivalent to Kotlin's `>` operator)
- * * [gte] — checks if a value is greater than _or equal to_ another value (equivalent to Kotlin's `>=` operator)
+ * * [eq] — checks if the sort key is equal to another value (equivalent to Kotlin's `==` operator)
+ * * [neq] — checks if two the sort key is _not_ equal to another value (equivalent to Kotlin's `!=` operator)
+ * * [lt] — checks if the sort key is less than another value (equivalent to Kotlin's `<` operator)
+ * * [lte] — checks if the sort key is less than _or equal to_ another value (equivalent to Kotlin's `<=` operator)
+ * * [gt] — checks if the sort key is greater than another value (equivalent to Kotlin's `>` operator)
+ * * [gte] — checks if the sort key is greater than _or equal to_ another value (equivalent to Kotlin's `>=` operator)
  *
  * For example:
  *
@@ -56,11 +56,16 @@ public interface SortKey
  * ```kotlin
  * // Checks whether the value of the sort key is between 40 and 60 (inclusive)
  * sortKey isIn 40..60
+ *
+ * // Checks whether the value of the sort key is between two binary values (inclusive)
+ * val minBinary: ByteArray = ...
+ * val maxBinary: ByteArray = ...
+ * sortKey.isBetween(minBinary, maxBinary)
  * ```
  *
  * # Prefixes
  *
- * The [startsWith] function enables expressing a prefix for the value of the sort key. For example:
+ * The [startsWith] function checks for a prefix in the value of the sort key. For example:
  *
  * ```kotlin
  * sortKey startsWith "abc" // Checks whether the value of the sort key starts with `"abc"`

hll/dynamodb-mapper/dynamodb-mapper/common/src/aws/sdk/kotlin/hll/dynamodbmapper/expressions/internal/KeyFilterImpl.kt

@@ -9,7 +9,19 @@ import aws.sdk.kotlin.hll.dynamodbmapper.items.ItemSchema
 import aws.sdk.kotlin.hll.dynamodbmapper.util.dynamicAttr
 import aws.sdk.kotlin.hll.dynamodbmapper.util.requireNull
 
-internal data class KeyFilterImpl(override val partitionKey: Any, override val sortKey: SortKeyExpr?) : KeyFilter
+internal data class KeyFilterImpl(override val partitionKey: Any, override val sortKey: SortKeyExpr?) : KeyFilter {
+    init {
+        require(
+            partitionKey is ByteArray ||
+                partitionKey is Number ||
+                partitionKey is String ||
+                partitionKey is UByte ||
+                partitionKey is UInt ||
+                partitionKey is ULong ||
+                partitionKey is UShort,
+        ) { "Partition key values must be either a ByteArray, Number, String, or an unsigned number type" }
+    }
+}
 
 internal fun KeyFilter.toExpression(schema: ItemSchema<*>) = when (schema) {
     is ItemSchema.CompositeKey<*, *, *> -> {

hll/hll-codegen/src/main/kotlin/aws/sdk/kotlin/hll/codegen/model/Member.kt

@@ -42,7 +42,7 @@ public data class Member(
 }
 
 /**
- * Gets the low-level [Structure] equivalent for this high-level structure
+ * Gets the low-level [Member] equivalent for this high-level member
  */
 @InternalSdkApi
 public val Member.lowLevel: Member

hll/hll-codegen/src/main/kotlin/aws/sdk/kotlin/hll/codegen/rendering/BuilderRenderer.kt

@@ -68,7 +68,6 @@ public class BuilderRenderer(
 
         write("#Lvar #L: #T = null", ctx.attributes.visibility, member.name, member.type.nullable())
 
-        ctx.info("For member $builderName.${member.name} dslInfo = $dslInfo")
         if (dslInfo != null) {
             blankLine()
             withBlock(