From 3dce6ff8da3487064bf6b976eeda5cc4ca65f5c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Fri, 11 Sep 2026 19:27:47 +0200 Subject: [PATCH] docs(dsl): Explicitly list the operators in the documentation of $set and $project --- .../kotlin/aggregation/stages/Project.kt | 20 ++++++++----------- .../kotlin/aggregation/stages/Set.kt | 6 ++++++ .../kotlin/aggregation/stages/Project.kt | 20 ++++++++----------- .../kotlin/aggregation/stages/Set.kt | 6 ++++++ 4 files changed, 28 insertions(+), 24 deletions(-) diff --git a/dsl-template/src/commonMain/kotlin/aggregation/stages/Project.kt b/dsl-template/src/commonMain/kotlin/aggregation/stages/Project.kt index 795ad976..d115efcc 100644 --- a/dsl-template/src/commonMain/kotlin/aggregation/stages/Project.kt +++ b/dsl-template/src/commonMain/kotlin/aggregation/stages/Project.kt @@ -45,18 +45,6 @@ interface HasProject : Pipeline { * * `_id` is kept even if not specified. To exclude it, see [ProjectStageOperators.excludeId]. * - * ### Difference with MongoDB - * - * In BSON, the `$project` stage can be used either for declaring an allow-list (by including fields, - * and possibly excluding the `_id`) or a block-list (by excluding fields). MongoDB doesn't allow a single stage - * usage to mix both usages. - * - * Because this is confusing, KtMongo splits both of these use-cases into two different methods. - * The former (selecting fields we want to keep) is performed by this method. - * The latter (selecting fields we want to remove) is performed by the stage [`$unset`][HasUnset.unset]. - * - * Note that just like in MongoDB, this stage can use all operators of the [`$set` stage][HasSet.set]. - * * ### Difference with $set * * This stage and the [`$set` stage][HasSet.set] are quite similar. In fact, both stages behave the same for fields @@ -95,6 +83,14 @@ interface HasProject : Pipeline { * ### External resources * * - [Official documentation](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project/) + * + * @param block The block defining the fields to include. + * - [ProjectStageOperators.include] Include a field in the document. + * - [ProjectStageOperators.excludeId] Exclude the `_id` field (included by default). + * - [ProjectStageOperators.exclude] Explicitly exclude a field (all fields are excluded by default). + * - [ProjectStageOperators.set] Overwrite the value of a field. + * - [ProjectStageOperators.setIf] Overwrite the value of a field if a condition is met. + * - [ProjectStageOperators.setUnless] Overwrite the value of a field if a condition is not met. */ @OptIn(DangerousMongoApi::class, LowLevelApi::class) fun project( diff --git a/dsl-template/src/commonMain/kotlin/aggregation/stages/Set.kt b/dsl-template/src/commonMain/kotlin/aggregation/stages/Set.kt index 33df0f1d..5de7ae0b 100644 --- a/dsl-template/src/commonMain/kotlin/aggregation/stages/Set.kt +++ b/dsl-template/src/commonMain/kotlin/aggregation/stages/Set.kt @@ -67,6 +67,12 @@ interface HasSet : Pipeline { * ### External resources * * - [Official documentation](https://www.mongodb.com/docs/manual/reference/operator/aggregation/set/) + * + * @param block The block defining the fields to set. + * - [SetStageOperators.set] Overwrite the value of a field. + * - [SetStageOperators.setIf] Overwrite the value of a field if a condition is met. + * - [SetStageOperators.setUnless] Overwrite the value of a field if a condition is not met. + * - [SetStageOperators.exclude] Remove a field. */ @OptIn(DangerousMongoApi::class, LowLevelApi::class) fun set( diff --git a/dsl/src/commonMain/kotlin/aggregation/stages/Project.kt b/dsl/src/commonMain/kotlin/aggregation/stages/Project.kt index 91605b3d..3d501c57 100644 --- a/dsl/src/commonMain/kotlin/aggregation/stages/Project.kt +++ b/dsl/src/commonMain/kotlin/aggregation/stages/Project.kt @@ -48,18 +48,6 @@ interface HasProject : Pipeline { * * `_id` is kept even if not specified. To exclude it, see [ProjectStageOperators.excludeId]. * - * ### Difference with MongoDB - * - * In BSON, the `$project` stage can be used either for declaring an allow-list (by including fields, - * and possibly excluding the `_id`) or a block-list (by excluding fields). MongoDB doesn't allow a single stage - * usage to mix both usages. - * - * Because this is confusing, KtMongo splits both of these use-cases into two different methods. - * The former (selecting fields we want to keep) is performed by this method. - * The latter (selecting fields we want to remove) is performed by the stage [`$unset`][HasUnset.unset]. - * - * Note that just like in MongoDB, this stage can use all operators of the [`$set` stage][HasSet.set]. - * * ### Difference with $set * * This stage and the [`$set` stage][HasSet.set] are quite similar. In fact, both stages behave the same for fields @@ -98,6 +86,14 @@ interface HasProject : Pipeline { * ### External resources * * - [Official documentation](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project/) + * + * @param block The block defining the fields to include. + * - [ProjectStageOperators.include] Include a field in the document. + * - [ProjectStageOperators.excludeId] Exclude the `_id` field (included by default). + * - [ProjectStageOperators.exclude] Explicitly exclude a field (all fields are excluded by default). + * - [ProjectStageOperators.set] Overwrite the value of a field. + * - [ProjectStageOperators.setIf] Overwrite the value of a field if a condition is met. + * - [ProjectStageOperators.setUnless] Overwrite the value of a field if a condition is not met. */ @OptIn(DangerousMongoApi::class, LowLevelApi::class) fun project( diff --git a/dsl/src/commonMain/kotlin/aggregation/stages/Set.kt b/dsl/src/commonMain/kotlin/aggregation/stages/Set.kt index ece0bb52..71723d63 100644 --- a/dsl/src/commonMain/kotlin/aggregation/stages/Set.kt +++ b/dsl/src/commonMain/kotlin/aggregation/stages/Set.kt @@ -70,6 +70,12 @@ interface HasSet : Pipeline { * ### External resources * * - [Official documentation](https://www.mongodb.com/docs/manual/reference/operator/aggregation/set/) + * + * @param block The block defining the fields to set. + * - [SetStageOperators.set] Overwrite the value of a field. + * - [SetStageOperators.setIf] Overwrite the value of a field if a condition is met. + * - [SetStageOperators.setUnless] Overwrite the value of a field if a condition is not met. + * - [SetStageOperators.exclude] Remove a field. */ @OptIn(DangerousMongoApi::class, LowLevelApi::class) fun set( -- 2.51.2