Add more docs for #bind (#46)

* Add more docs for `#bind`

* fix

Author: stephencelis

Package.resolved

@@ -78,8 +78,8 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/pointfreeco/swift-snapshot-testing",
       "state" : {
-        "revision" : "1be8144023c367c5de701a6313ed29a3a10bf59b",
-        "version" : "1.18.3"
+        "revision" : "37230a37e83f1b7023be08e1b1a2603fcb1567fb",
+        "version" : "1.18.4"
       }
     },
     {

Sources/StructuredQueriesCore/Documentation.docc/Articles/DefiningYourSchema.md

@@ -143,14 +143,19 @@ generated when writing queries will correctly use `"is_completed"`.
 
 ### Custom data types
 
-There are many data types that do not have native support in SQLite. For these data types you must
-define a conformance to ``QueryBindable`` in order to translate values to a format that SQLite does
-understand. The library comes with conformances to aid in representing dates, UUIDs, and JSON, and
-you can define your own conformances for your own custom data types.
+StructuredQueries provides support for many basic Swift data types out of the box, like strings,
+integers, doubles, bytes, and booleans, but you may want to represent custom, domain specific types
+with your table's columns, instead. For these data types you must either define a conformance to
+``QueryBindable`` to translate values to a format that the library does understand, or provide a
+``QueryRepresentable`` type that wraps your domain type.
+
+The library comes with several `QueryRepresentable` conformances to aid in representing dates,
+UUIDs, and JSON, and you can define your own conformances for your own custom data types.
 
 #### Dates
 
-SQLite does not have a native date type, and instead has 3 different ways to represent dates:
+While some relational databases, like MySQL and Postgres, have native support for dates, SQLite
+does _not_. Instead, it has 3 different ways to represent dates:
 
   * Text column interpreted as ISO-8601-formatted string.
   * Int column interpreted as number of seconds since Unix epoch.
@@ -203,6 +208,14 @@ And StructuredQueries will take care of formatting the value for the database:
   }
 }
 
+When querying against a date column with a Swift date, you will need to explicitly bundle up the
+Swift date into the appropriate representation to use various query helpers. This can be done using
+the `#bind` macro:
+
+```swift
+Reminder.where { $0.created > #bind(startDate) }
+```
+
 #### UUID
 
 SQLite also does not have native support for UUIDs. If you try to use a UUID in your tables you
@@ -238,6 +251,14 @@ translate the UUID to text:
 }
 ```
 
+When querying against a UUID column with a Swift UUID, you will need to explicitly bundle up the
+Swift UUID into the appropriate representation to use various query helpers. This can be done using
+the `#bind` macro:
+
+```swift
+Reminder.where { $0.id != #bind(reminder.id) }
+```
+
 #### RawRepresentable
 
 Simple data types, in particular ones conforming to `RawRepresentable` whose `RawValue` is a string

Tests/StructuredQueriesMacrosTests/Support/SnapshotTests.swift

@@ -8,16 +8,16 @@ import Testing
 @Suite(
   .serialized,
   .macros(
-    record: .failed,
-    macros: [
+    [
       "_Draft": TableMacro.self,
       "bind": BindMacro.self,
       "Column": ColumnMacro.self,
       "Ephemeral": EphemeralMacro.self,
-      "Table": TableMacro.self,
       "Selection": SelectionMacro.self,
       "sql": SQLMacro.self,
-    ]
+      "Table": TableMacro.self,
+    ],
+    record: .failed
   )
 ) struct SnapshotTests {}
 

Tests/StructuredQueriesMacrosTests/TableMacroTests.swift

@@ -229,18 +229,18 @@ extension SnapshotTests {
           var baz: Int
         }
 
-        extension Bar: StructuredQueries.Table {
-          public struct TableColumns: StructuredQueries.TableDefinition {
+        extension Bar: StructuredQueriesCore.Table {
+          public struct TableColumns: StructuredQueriesCore.TableDefinition {
             public typealias QueryValue = Bar
-            public let baz = StructuredQueries.TableColumn<QueryValue, Int>("baz", keyPath: \QueryValue.baz)
-            public static var allColumns: [any StructuredQueries.TableColumnExpression] {
+            public let baz = StructuredQueriesCore.TableColumn<QueryValue, Int>("baz", keyPath: \QueryValue.baz)
+            public static var allColumns: [any StructuredQueriesCore.TableColumnExpression] {
               [QueryValue.columns.baz]
             }
           }
           public static let columns = TableColumns()
           public static let tableName = "bar"
           public static let schemaName: Swift.String? = "foo"
-          public init(decoder: inout some StructuredQueries.QueryDecoder) throws {
+          public init(decoder: inout some StructuredQueriesCore.QueryDecoder) throws {
             let baz = try decoder.decode(Int.self)
             guard let baz else {
               throw QueryDecodingError.missingRequiredColumn