docs(documentdb): update descriptions (#15)

* docs(documentdb): update descriptions

* Apply suggestions from code review

Co-authored-by: Will Russell <will@wrussell.co.uk>

---------

Co-authored-by: Will Russell <will@wrussell.co.uk>

Author: aj-emerich

src/main/java/io/kestra/plugin/documentdb/AbstractDocumentDBTask.java

@@ -22,36 +22,36 @@
 public abstract class AbstractDocumentDBTask extends Task {
 
     @Schema(
-        title = "DocumentDB host",
-        description = "The HTTP endpoint URL of your DocumentDB instance"
+        title = "DocumentDB endpoint",
+        description = "Base HTTPS endpoint for the DocumentDB REST API; trailing slash is trimmed before calling `/data/v1/action/*`."
     )
     @NotNull
     protected Property<String> host;
 
     @Schema(
-        title = "Database name",
-        description = "The name of the database"
+        title = "Target database",
+        description = "Database name used for the operation; expressions are rendered at runtime."
     )
     @NotNull
     protected Property<String> database;
 
     @Schema(
-        title = "Collection name",
-        description = "The name of the collection"
+        title = "Target collection",
+        description = "Collection inside the database where the action is performed."
     )
     @NotNull
     protected Property<String> collection;
 
     @Schema(
-        title = "Username",
-        description = "DocumentDB username for authentication"
+        title = "HTTP username",
+        description = "Basic-auth username for the DocumentDB API; prefer providing via secret."
     )
     @NotNull
     protected Property<String> username;
 
     @Schema(
-        title = "Password",
-        description = "DocumentDB password for authentication"
+        title = "HTTP password",
+        description = "Basic-auth password for the DocumentDB API; prefer providing via secret."
     )
     @NotNull
     protected Property<String> password;

src/main/java/io/kestra/plugin/documentdb/Delete.java

@@ -26,8 +26,8 @@
 @Getter
 @NoArgsConstructor
 @Schema(
-    title = "Delete documents from a DocumentDB collection.",
-    description = "Delete one or more documents from a DocumentDB collection that match the filter criteria."
+    title = "Delete documents from DocumentDB",
+    description = "Remove one document (default) or every match when `deleteMany` is true. An empty filter with `deleteMany` can wipe the collection, so set filters carefully."
 )
 @Plugin(
     examples = {
@@ -101,14 +101,14 @@
 public class Delete extends AbstractDocumentDBTask implements RunnableTask<Delete.Output> {
 
     @Schema(
-        title = "Filter criteria",
-        description = "MongoDB-style filter to select which documents to delete. Example: {\"status\": \"inactive\", \"age\": {\"$gte\": 18}}"
+        title = "Filter query",
+        description = "MongoDB-style filter that selects documents to delete. Rendered at runtime; an empty filter with `deleteMany` deletes every document. Example: `{\\\"status\\\": \\\"inactive\\\", \\\"age\\\": {\\\"$gte\\\": 18}}`"
     )
     private Property<Map<String, Object>> filter;
 
     @Schema(
-        title = "Delete multiple documents",
-        description = "If true, deletes all documents matching the filter (deleteMany). If false, deletes only the first match (deleteOne)."
+        title = "Delete all matches",
+        description = "Set to true to delete every document matching the filter; default false deletes only the first match."
     )
     @Builder.Default
     private Property<Boolean> deleteMany = Property.ofValue(false);
@@ -161,9 +161,9 @@ public Output run(RunContext runContext) throws Exception {
     @Getter
     public static class Output implements io.kestra.core.models.tasks.Output {
         @Schema(
-            title = "Number of documents deleted",
-            description = "Total count of documents that were successfully deleted"
+            title = "Deleted document count",
+            description = "Total number of documents removed by the operation."
         )
         private final Integer deletedCount;
     }
-}
+}

src/main/java/io/kestra/plugin/documentdb/Insert.java

@@ -30,8 +30,8 @@
 @Getter
 @NoArgsConstructor
 @Schema(
-    title = "Insert documents into a DocumentDB collection.",
-    description = "Insert one or more documents into a DocumentDB collection. Can insert a single document or multiple documents (max 10) in one operation."
+    title = "Insert documents into DocumentDB",
+    description = "Write one document or a batch (max 10) to the target collection. Rendered inputs support expressions; choose either `document` or `documents`."
 )
 @Plugin(
     examples = {
@@ -122,14 +122,14 @@
 public class Insert extends AbstractDocumentDBTask implements RunnableTask<Insert.Output> {
 
     @Schema(
-        title = "Document for single insert",
-        description = "Document to insert (for single document insertion). Use this OR `documents`, not both."
+        title = "Single document payload",
+        description = "Document to insert when sending one record. Mutually exclusive with `documents`; values are rendered before execution."
     )
     private Property<Map<String, Object>> document;
 
     @Schema(
-        title = "Multiple documents",
-        description = "List of documents to insert (max " + MAX_DOCUMENTS_PER_INSERT + "). Use this OR `document`, not both."
+        title = "Batch documents",
+        description = "List of documents to insert (max " + MAX_DOCUMENTS_PER_INSERT + "). Mutually exclusive with `document`; order is preserved."
     )
     private Property<List<Map<String, Object>>> documents;
 
@@ -194,21 +194,21 @@ public Output run(RunContext runContext) throws Exception {
     @Getter
     public static class Output implements io.kestra.core.models.tasks.Output {
         @Schema(
-            title = "Inserted document ID",
-            description = "The ID of the first inserted document (for single insert or first of multiple)"
+            title = "First inserted ID",
+            description = "ID of the single document or the first item in a batch; null if none returned."
         )
         private final String insertedId;
 
         @Schema(
-            title = "All inserted document IDs",
-            description = "List of all inserted document IDs"
+            title = "Inserted document IDs",
+            description = "List of all document IDs acknowledged by DocumentDB."
         )
         private final List<String> insertedIds;
 
         @Schema(
-            title = "Number of documents inserted",
-            description = "Total count of documents successfully inserted"
+            title = "Inserted document count",
+            description = "Total number of documents the API reports as inserted."
         )
         private final Integer insertedCount;
     }
-}
+}

src/main/java/io/kestra/plugin/documentdb/Read.java

@@ -36,8 +36,8 @@
 @Getter
 @NoArgsConstructor
 @Schema(
-    title = "Read documents from a DocumentDB collection.",
-    description = "Read documents from a DocumentDB collection with optional filtering, limiting, and aggregation support."
+    title = "Read documents from DocumentDB",
+    description = "Query a collection with an optional filter, skip/limit, or aggregation pipeline. Results are rendered into the selected `fetchType` output; default FETCH returns all rows."
 )
 @Plugin(
     examples = {
@@ -135,31 +135,31 @@ public class Read extends AbstractDocumentDBTask implements RunnableTask<Read.Ou
 
     @Schema(
         title = "Filter",
-        description = "MongoDB-style filter criteria to apply to the query. Example: {\"status\": \"active\", \"age\": {\"$gte\": 18}}"
+        description = "MongoDB-style filter for the find query, rendered at runtime. Leave empty to scan the full collection."
     )
     private Property<Map<String, Object>> filter;
 
     @Schema(
         title = "Aggregation pipeline",
-        description = "MongoDB aggregation pipeline stages. If provided, this will execute an aggregation instead of a simple find."
+        description = "MongoDB aggregation stages to run instead of a simple find. Overrides `filter`, `skip`, and `limit`."
     )
     private Property<List<Map<String, Object>>> aggregationPipeline;
 
     @Schema(
         title = "Limit",
-        description = "Maximum number of documents to return"
+        description = "Maximum number of documents to return; optional server-side cap."
     )
     private Property<Integer> limit;
 
     @Schema(
         title = "Skip",
-        description = "Number of documents to skip"
+        description = "Number of documents to skip before returning results."
     )
     private Property<Integer> skip;
 
     @Schema(
         title = "Fetch type",
-        description = "How to handle query results. STORE: store all rows to a file, FETCH: output all rows as output variable, FETCH_ONE: output the first row, NONE: do nothing"
+        description = "Controls result handling (default FETCH). STORE writes all rows to Kestra internal storage as Ion, FETCH outputs all rows, FETCH_ONE outputs only the first row, NONE skips output."
     )
     @NotNull
     @Builder.Default
@@ -285,26 +285,27 @@ private static class StoredResult {
     @Getter
     public static class Output implements io.kestra.core.models.tasks.Output {
         @Schema(
-            title = "Map containing the first row of fetched data",
-            description = "Only populated if fetchType is FETCH_ONE."
+            title = "First row",
+            description = "First matching document when fetchType is FETCH_ONE; null if no results."
         )
         private final Map<String, Object> row;
 
         @Schema(
-            title = "List of map containing rows of fetched data",
-            description = "Only populated if fetchType is FETCH."
+            title = "Rows",
+            description = "All returned documents when fetchType is FETCH."
         )
         private final List<Map<String, Object>> rows;
 
         @Schema(
-            title = "The URI of the result file on Kestra's internal storage (.ion file / Amazon Ion formatted text file)",
-            description = "Only populated if fetchType is STORE."
+            title = "Result file URI",
+            description = "URI in Kestra internal storage for the Ion result file; only set when fetchType is STORE."
         )
         private final URI uri;
 
         @Schema(
-            title = "The number of documents returned by the operation"
+            title = "Returned document count",
+            description = "Number of documents fetched or stored."
         )
         private final Long size;
     }
-}
+}

src/main/java/io/kestra/plugin/documentdb/Update.java

@@ -26,8 +26,8 @@
 @Getter
 @NoArgsConstructor
 @Schema(
-    title = "Update documents in a DocumentDB collection.",
-    description = "Update one or more documents in a DocumentDB collection that match the filter criteria."
+    title = "Update documents in DocumentDB",
+    description = "Apply Mongo-style update operators to matching documents. Defaults to updating one document; set `updateMany` to true to affect all matches. An empty filter with `updateMany` can update every document."
 )
 @Plugin(
     examples = {
@@ -111,21 +111,21 @@
 public class Update extends AbstractDocumentDBTask implements RunnableTask<Update.Output> {
 
     @Schema(
-        title = "Filter criteria",
-        description = "MongoDB-style filter to select which documents to update. Example: {\"status\": \"pending\", \"age\": {\"$gte\": 18}}"
+        title = "Filter query",
+        description = "MongoDB-style filter that selects documents to update. Rendered at runtime; an empty filter with `updateMany` updates all documents."
     )
     private Property<Map<String, Object>> filter;
 
     @Schema(
         title = "Update operations",
-        description = "MongoDB-style update operations to apply. Example: {\"$set\": {\"status\": \"active\"}, \"$inc\": {\"count\": 1}}"
+        description = "Required MongoDB update document (e.g., `$set`, `$inc`), rendered before sending to the API."
     )
     @NotNull
     private Property<Map<String, Object>> update;
 
     @Schema(
-        title = "Update multiple documents",
-        description = "If true, updates all documents matching the filter (updateMany). If false, updates only the first match (updateOne)."
+        title = "Update all matches",
+        description = "Set to true to update every document matching the filter; default false updates only the first match."
     )
     @Builder.Default
     private Property<Boolean> updateMany = Property.ofValue(false);
@@ -188,21 +188,21 @@ public Output run(RunContext runContext) throws Exception {
     @Getter
     public static class Output implements io.kestra.core.models.tasks.Output {
         @Schema(
-            title = "Number of documents matched",
-            description = "Total count of documents that matched the filter criteria"
+            title = "Matched document count",
+            description = "Number of documents that matched the filter."
         )
         private final Integer matchedCount;
 
         @Schema(
-            title = "Number of documents modified",
-            description = "Total count of documents that were actually modified"
+            title = "Modified document count",
+            description = "Number of documents actually updated."
         )
         private final Integer modifiedCount;
 
         @Schema(
             title = "Upserted document ID",
-            description = "ID of the document that was created if upsert was enabled and no match was found"
+            description = "ID of the inserted document when upsert occurs; null otherwise."
         )
         private final String upsertedId;
     }
-}
+}