Clean up declarations in docs (#201)

Add missing declarations to docs, fix mis-specified declarations. update README.

Author: gwynne

README.md

@@ -1,14 +1,15 @@
-<p align="center">
+<div align="center">
 <img src="https://design.vapor.codes/images/vapor-sqlkit.svg" height="96" alt="SQLKit">
 <br>
-<br>
-<a href="https://docs.vapor.codes/4.0/"><img src="https://design.vapor.codes/images/readthedocs.svg" alt="Documentation"></a>
-<a href="https://discord.gg/vapor"><img src="https://design.vapor.codes/images/discordchat.svg" alt="Team Chat"></a>
-<a href="LICENSE"><img src="https://design.vapor.codes/images/mitlicense.svg" alt="MIT License"></a>
-<a href="https://github.com/vapor/sql-kit/actions/workflows/test.yml"><img src="https://img.shields.io/github/actions/workflow/status/vapor/sql-kit/test.yml?event=push&style=plastic&logo=github&label=tests&logoColor=%23ccc" alt="Continuous Integration"></a>
-<a href="https://codecov.io/github/vapor/sql-kit"><img src="https://img.shields.io/codecov/c/github/vapor/sql-kit?style=plastic&logo=codecov&label=codecov" alt="Code Coverage"></a>
-<a href="https://swift.org"><img src="https://design.vapor.codes/images/swift60up.svg" alt="Swift 6.0+"></a>
-</p>
+
+[![Documentation](https://design.vapor.codes/images/readthedocs.svg)](https://docs.vapor.codes/4.0/)
+[![Team Chat](https://design.vapor.codes/images/discordchat.svg)](https://discord.gg/vapor)
+[![MIT License](https://design.vapor.codes/images/mitlicense.svg)](LICENSE)
+[![Continuous Integration](https://img.shields.io/github/actions/workflow/status/vapor/sql-kit/test.yml?event=push&style=plastic&logo=github&label=tests&logoColor=ccc)](https://github.com/vapor/sql-kit/actions/workflows/test.yml)
+[![Code Coverage](https://img.shields.io/codecov/c/github/vapor/sql-kit?style=plastic&logo=codecov&label=codecov)](https://codecov.io/github/vapor/sql-kit)
+[![Swift 6.1+](https://design.vapor.codes/images/swift61up.svg)](https://swift.org)
+
+</div>
 
 <br>
 

Sources/SQLKit/Builders/Prototypes/SQLQueryFetcher.swift

@@ -128,9 +128,13 @@ extension SQLQueryFetcher {
     /// If `self` conforms to ``SQLPartialResultBuilder``, ``SQLPartialResultBuilder/limit(_:)`` is used to avoid
     /// loading more rows than necessary from the database.
     ///
+    /// > Note: This method returns `Optional<any SQLRow>` rather than the semantically identical `(any SQLRow)?`
+    /// > due to a bug in Swift DocC causing it to become confused by the latter. The syntactic sugar will be
+    /// > restored once the bug is fixed.
+    ///
     /// - Returns: The first output row, if any.
     @inlinable
-    public func first() async throws -> (any SQLRow)? {
+    public func first() async throws -> Optional<any SQLRow> {
         (self as? any SQLPartialResultBuilder)?.limit(1)
         nonisolated(unsafe) var rows = [any SQLRow]()
         try await self.run { if rows.isEmpty { rows.append($0) } }

Sources/SQLKit/Docs.docc/BasicUsage.md

@@ -166,16 +166,16 @@ Notice that `Encodable` values are automatically bound as parameters instead of
 
 The select builder includes the following methods (most of which have numerous variations):
 
-- `columns()` (specify a list of columns and/or expressions to return)
-- `from()` (specify a table to select from)
-- `join()` (specify additional tables and how to relate them to others)
-- `where()` and `orWhere()` (specify conditions that narrow down the possible results)
-- `limit()` and `offset()` (specify a limited and/or offsetted range of results to return)
-- `orderBy()` (specify how to sort results before returning them)
-- `groupBy()` (specify columns and/or expressions for aggregating results)
-- `having()` and `orHaving()` (specify secondary conditions to apply to the results after aggregation)
-- `distinct()` (specify coalescing of duplicate results)
-- `for()` and `lockingClause()` (specify locking behavior for rows that appear in results)
+- ``SQLSelectBuilder/columns(_:)-([SQLExpression])`` (specify a list of columns and/or expressions to return)
+- ``SQLSelectBuilder/from(_:)-(String)`` (specify a table to select from)
+- ``SQLSelectBuilder/join(_:method:on:_:_:)-(SQLExpression,_,_,_,_)`` (specify additional tables and how to relate them to others)
+- ``SQLSelectBuilder/where(_:_:_:)-(SQLExpression,SQLBinaryOperator,_)`` and ``SQLSelectBuilder/orWhere(_:_:_:)-(SQLExpression,SQLBinaryOperator,_)`` (specify conditions that narrow down the possible results)
+- ``SQLSelectBuilder/limit(_:)`` and ``SQLSelectBuilder/offset(_:)`` (specify a limited and/or offsetted range of results to return)
+- ``SQLSelectBuilder/orderBy(_:_:)-(String,_)`` (specify how to sort results before returning them)
+- ``SQLSelectBuilder/groupBy(_:)-(SQLExpression)`` (specify columns and/or expressions for aggregating results)
+- ``SQLSelectBuilder/having(_:_:_:)-(SQLExpression,SQLBinaryOperator,_)`` and ``SQLSelectBuilder/orHaving(_:_:_:)-(SQLExpression,SQLBinaryOperator,_)`` (specify secondary conditions to apply to the results after aggregation)
+- ``SQLSelectBuilder/distinct()`` (specify coalescing of duplicate results)
+- ``SQLSelectBuilder/for(_:)`` and ``SQLSelectBuilder/lockingClause(_:)`` (specify locking behavior for rows that appear in results)
 
 Conditional expressions provided to `where()` or `having()` are joined with `AND`. Corresponding `orWhere()` and `orHaving()` methods join conditions with `OR` instead.
 

Sources/SQLKit/Docs.docc/SQLKit.md

@@ -43,6 +43,8 @@ SQLKit does _not_ provide facilities for creating or managing database connectio
 
 - ``SQLAliasedColumnListBuilder``
 - ``SQLColumnUpdateBuilder``
+- ``SQLCommonTableExpressionBuilder``
+- ``SQLCommonUnionBuilder``
 - ``SQLJoinBuilder``
 - ``SQLPartialResultBuilder``
 - ``SQLPredicateBuilder``
@@ -75,6 +77,7 @@ SQLKit does _not_ provide facilities for creating or managing database connectio
 - ``SQLSelectBuilder``
 - ``SQLSubqueryBuilder``
 - ``SQLUnionBuilder``
+- ``SQLUnionSubqueryBuilder``
 - ``SQLUpdateBuilder``
 
 ### Syntactic Expressions
@@ -109,6 +112,8 @@ SQLKit does _not_ provide facilities for creating or managing database connectio
 - ``SQLColumnAssignment``
 - ``SQLColumnConstraintAlgorithm``
 - ``SQLColumnDefinition``
+- ``SQLCommonTableExpression``
+- ``SQLCommonTableExpressionGroup``
 - ``SQLConflictAction``
 - ``SQLConflictResolutionStrategy``
 - ``SQLDropBehavior``
@@ -124,6 +129,7 @@ SQLKit does _not_ provide facilities for creating or managing database connectio
 - ``SQLSubquery``
 - ``SQLTableConstraintAlgorithm``
 - ``SQLUnionJoiner``
+- ``SQLUnionSubquery``
 
 ### Query Expressions
 

Sources/SQLKit/Docs.docc/SQLQueryFetcher+ExtensionDocs.md

@@ -11,15 +11,15 @@
 
 ### Getting All Rows
 
-- ``SQLQueryFetcher/all(decoding:with:)->[D]``
+- ``SQLQueryFetcher/all()->[SQLRow]``
 - ``SQLQueryFetcher/all(decoding:)->[D]``
 - ``SQLQueryFetcher/all(decoding:prefix:keyDecodingStrategy:userInfo:)->[D]``
 - ``SQLQueryFetcher/all(decoding:with:)->[D]``
 - ``SQLQueryFetcher/all(decodingColumn:as:)->[D]``
 
 ### Getting One Row
 
-- ``SQLQueryFetcher/first()->EventLoopFuture<(SQLRow)?>``
+- ``SQLQueryFetcher/first()->SQLRow?``
 - ``SQLQueryFetcher/first(decoding:)->D?``
 - ``SQLQueryFetcher/first(decoding:prefix:keyDecodingStrategy:userInfo:)->D?``
 - ``SQLQueryFetcher/first(decoding:with:)->D?``