Update docs (#148)

- Stub an article for full-text search
- Fix outdated DocC symbols
- Miscellaneous fixes

One breaking change: `jsonGroupArray`'s `isDistinct` parameter was
renamed to `distinct`. Applying fix-it should be enough to migrate and
we're pre-1.0, so not sure a deprecated overload is worth it.

Author: stephencelis

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

@@ -0,0 +1,26 @@
+# Full-text search
+
+## Overview
+
+StructuredQueries comes with built-in support for SQLite's FTS5 module.
+
+## Topics
+
+### Virtual tables
+
+- ``FTS5``
+
+### Performing searches
+
+- ``TableDefinition/match(_:)``
+- ``TableColumnExpression/match(_:)``
+
+### Ranking searches
+
+- ``TableDefinition/rank``
+- ``TableDefinition/bm25(_:)``
+
+### Highlighting results
+
+- ``TableColumnExpression/highlight(_:_:)``
+- ``TableColumnExpression/snippet(_:_:_:_:)``

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

@@ -411,8 +411,7 @@ Or you can conditionally upsert from given indexed columns using `onConflict:doU
   }
 }
 
-Upsert clauses have an additional, special ``Updates/excluded`` qualifier for referring to a row
-that failed to insert.
+Upsert clauses have an additional, special argument for referring to a row that failed to insert.
 
 ```swift
 @Row {
@@ -425,8 +424,8 @@ that failed to insert.
     } onConflict: {
       $0.title
     } doUpdate: {
-      $0.isCompleted = $0.excluded.isCompleted
-      $0.priority = $0.excluded.priority
+      $0.isCompleted = $1.isCompleted
+      $0.priority = $1.priority
     }
     ```
   }
@@ -460,7 +459,6 @@ that failed to insert.
 
 ### Inserting drafts
 
-- ``PrimaryKeyedTable/insert(or:_:values:onConflictDoUpdate:where:)``
 - ``PrimaryKeyedTable/upsert(or:values:)``
 
 ### Inserting from a select

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

@@ -116,7 +116,6 @@ Explore the full list of operators below.
 - ``QueryExpression/+(_:_:)``
 - ``QueryExpression/like(_:escape:)``
 - ``QueryExpression/glob(_:)``
-- ``QueryExpression/match(_:)``
 - ``QueryExpression/hasPrefix(_:)``
 - ``QueryExpression/hasSuffix(_:)``
 - ``QueryExpression/contains(_:)``
@@ -128,7 +127,7 @@ Explore the full list of operators below.
 
 - ``QueryExpression/in(_:)``
 - ``Statement/contains(_:)``
-- ``Statement/exists()``
+- ``PartialSelectStatement/exists()``
 - ``Swift/Array``
 - ``Swift/ClosedRange``
 

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

@@ -133,7 +133,7 @@ extension Reminder.TableColumns {
 ```
 
 Then you can use these helpers when building a query. For example, you can use
-``PrimaryKeyedTableDefinition/count(filter:)`` to count the number of past due, current and
+``PrimaryKeyedTableDefinition/count(distinct:filter:)`` to count the number of past due, current and
 scheduled reminders in one single query like so:
 
 @Row {
@@ -409,8 +409,8 @@ struct Row {
 
 This allows the query to serialize the associated rows into JSON, which are then deserialized into
 a `Row` type. To construct such a query you can use the
-``PrimaryKeyedTableDefinition/jsonGroupArray(order:filter:)`` property that is defined on the
-columns of [primary keyed tables](<doc:PrimaryKeyedTables>):
+``PrimaryKeyedTableDefinition/jsonGroupArray(distinct:order:filter:)`` property that is defined on
+the columns of [primary keyed tables](<doc:PrimaryKeyedTables>):
 
 ```swift
 RemindersList
@@ -471,8 +471,8 @@ RemindersList
   .select {
     Row.Columns(
       remindersList: $0,
-      milestones: $1.jsonGroupArray(isDistinct: true),
-      reminders: $2.jsonGroupArray(isDistinct: true)
+      milestones: $1.jsonGroupArray(distinct: true),
+      reminders: $2.jsonGroupArray(distinct: true)
     )
   }
 ```

Sources/StructuredQueriesCore/Documentation.docc/Extensions/PrimaryKeyedTable.md

@@ -134,8 +134,6 @@ Reminder.delete(reminder)
 
 - ``Draft``
 - ``find(_:)``
-- ``insert(or:_:values:onConflict:where:doUpdate:where:)``
-- ``insert(or:_:values:onConflictDoUpdate:where:)``
 - ``update(or:_:)``
 - ``upsert(or:values:)``
 - ``delete(_:)``

Sources/StructuredQueriesCore/Documentation.docc/Extensions/QueryExpression.md

@@ -27,8 +27,8 @@
 ### JSON functions
 
 - ``jsonArrayLength()``
-- ``jsonGroupArray(order:filter:)``
-- ``jsonObject()``
+- ``jsonGroupArray(distinct:order:filter:)``
+- ``TableDefinition/jsonObject()``
 - ``jsonPatch(_:)``
 
 ### Optionality

Sources/StructuredQueriesCore/Documentation.docc/StructuredQueriesCore.md

@@ -138,4 +138,5 @@ reading to learn more about building SQL with StructuredQueries.
 
 ### Advanced
 
+- <doc:FullTextSearch>
 - <doc:Integration>

Sources/StructuredQueriesCore/PrimaryKeyed.swift

@@ -67,7 +67,10 @@ extension TableDefinition where QueryValue: TableDraft {
 extension PrimaryKeyedTableDefinition {
   /// A query expression representing the number of rows in this table.
   ///
-  /// - Parameter filter: A `FILTER` clause to apply to the aggregation.
+  /// - Parameters:
+  ///   - isDistinct: Whether or not to include a `DISTINCT` clause, which filters duplicates from
+  ///     the aggregation.
+  ///   - filter: A `FILTER` clause to apply to the aggregation.
   /// - Returns: An expression representing the number of rows in this table.
   public func count(
     distinct isDistinct: Bool = false,

Sources/StructuredQueriesCore/SQLite/JSONFunctions.swift

@@ -42,7 +42,7 @@ extension QueryExpression where QueryValue: Codable & QueryBindable {
   ///   - filter: A `FILTER` clause to apply to the aggregation.
   /// - Returns: A JSON array aggregate of this expression.
   public func jsonGroupArray(
-    isDistinct: Bool = false,
+    distinct isDistinct: Bool = false,
     order: (some QueryExpression)? = Bool?.none,
     filter: (some QueryExpression<Bool>)? = Bool?.none
   ) -> some QueryExpression<[QueryValue].JSONRepresentation> {
@@ -108,7 +108,7 @@ extension PrimaryKeyedTableDefinition where QueryValue: Codable {
   ///   - filter: A `FILTER` clause to apply to the aggregation.
   /// - Returns: A JSON array aggregate of this table.
   public func jsonGroupArray(
-    isDistinct: Bool = false,
+    distinct isDistinct: Bool = false,
     order: (some QueryExpression)? = Bool?.none,
     filter: (some QueryExpression<Bool>)? = Bool?.none
   ) -> some QueryExpression<[QueryValue].JSONRepresentation> {
@@ -174,7 +174,7 @@ extension PrimaryKeyedTableDefinition where QueryValue: _OptionalProtocol & Coda
   ///   - filter: A `FILTER` clause to apply to the aggregation.
   /// - Returns: A JSON array aggregate of this table.
   public func jsonGroupArray<Wrapped: Codable>(
-    isDistinct: Bool = false,
+    distinct isDistinct: Bool = false,
     order: (some QueryExpression)? = Bool?.none,
     filter: (some QueryExpression<Bool>)? = Bool?.none
   ) -> some QueryExpression<[Wrapped].JSONRepresentation>

Tests/StructuredQueriesTests/JSONFunctionsTests.swift

@@ -43,7 +43,7 @@ extension SnapshotTests {
     @Test func jsonGroupArrayDisctinct() {
       assertQuery(
         Reminder.select {
-          $0.priority.jsonGroupArray(isDistinct: true)
+          $0.priority.jsonGroupArray(distinct: true)
         }
       ) {
         """
@@ -221,8 +221,8 @@ extension SnapshotTests {
           .select {
             RemindersListRow.Columns(
               remindersList: $0,
-              milestones: $1.jsonGroupArray(isDistinct: true),
-              reminders: $2.jsonGroupArray(isDistinct: true)
+              milestones: $1.jsonGroupArray(distinct: true),
+              reminders: $2.jsonGroupArray(distinct: true)
             )
           }
           .limit(1)