Skip to content

Clean up declarations in docs #201

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gwynne merged 1 commit into from
Jul 14, 2026
Merged

Clean up declarations in docs #201

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 10 additions & 9 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>

Expand Down
6 changes: 5 additions & 1 deletion Sources/SQLKit/Builders/Prototypes/SQLQueryFetcher.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

@MahdiBM MahdiBM Jul 14, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I doubt this comment was actually needed but I guess it doesn't hurt either.

@gwynne gwynne Jul 14, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If nothing else it serves to remind me why the style violation is there. 🤷‍♀️

/// > 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) } }
Expand Down
20 changes: 10 additions & 10 deletions Sources/SQLKit/Docs.docc/BasicUsage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
6 changes: 6 additions & 0 deletions Sources/SQLKit/Docs.docc/SQLKit.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,8 @@ SQLKit does _not_ provide facilities for creating or managing database connectio

- ``SQLAliasedColumnListBuilder``
- ``SQLColumnUpdateBuilder``
- ``SQLCommonTableExpressionBuilder``
- ``SQLCommonUnionBuilder``
- ``SQLJoinBuilder``
- ``SQLPartialResultBuilder``
- ``SQLPredicateBuilder``
Expand Down Expand Up @@ -75,6 +77,7 @@ SQLKit does _not_ provide facilities for creating or managing database connectio
- ``SQLSelectBuilder``
- ``SQLSubqueryBuilder``
- ``SQLUnionBuilder``
- ``SQLUnionSubqueryBuilder``
- ``SQLUpdateBuilder``

### Syntactic Expressions
Expand Down Expand Up @@ -109,6 +112,8 @@ SQLKit does _not_ provide facilities for creating or managing database connectio
- ``SQLColumnAssignment``
- ``SQLColumnConstraintAlgorithm``
- ``SQLColumnDefinition``
- ``SQLCommonTableExpression``
- ``SQLCommonTableExpressionGroup``
- ``SQLConflictAction``
- ``SQLConflictResolutionStrategy``
- ``SQLDropBehavior``
Expand All @@ -124,6 +129,7 @@ SQLKit does _not_ provide facilities for creating or managing database connectio
- ``SQLSubquery``
- ``SQLTableConstraintAlgorithm``
- ``SQLUnionJoiner``
- ``SQLUnionSubquery``

### Query Expressions

Expand Down
4 changes: 2 additions & 2 deletions Sources/SQLKit/Docs.docc/SQLQueryFetcher+ExtensionDocs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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?``
Expand Down
Loading