docs(dropbox): update descriptions (#16)

Author: aj-emerich

src/main/java/io/kestra/plugin/dropbox/files/Copy.java

@@ -49,30 +49,34 @@
         )
     }
 )
-@Schema(title = "Copy a file or folder to a different location in Dropbox.")
+@Schema(
+    title = "Copy Dropbox file or folder",
+    description = "Copies an item to another Dropbox path. Paths must start with `/`; can be read from kestra:// URIs. Conflicts can autorename (default false)."
+)
 public class Copy extends Task implements RunnableTask<Copy.Output> {
 
-    @Schema(title = "Dropbox access token.")
+    @Schema(title = "Dropbox access token", description = "Token must allow reading source and writing destination.")
     @NotNull
     private Property<String> accessToken;
 
     @Schema(
-        title = "The path of the file or folder to be copied.",
-        description = "Can be a direct path as a string, or a Kestra internal storage URI (kestra://...) of a file containing the path."
+        title = "Source path",
+        description = "Literal Dropbox path or kestra:// URI containing the path. Must start with `/`."
     )
     @NotNull
     private Object from;
 
     @Schema(
-        title = "The destination path where the file or folder should be copied.",
-        description = "Can be a direct path as a string, or a Kestra internal storage URI (kestra://...) of a file containing the path."
+        title = "Destination path",
+        description = "Literal Dropbox path or kestra:// URI containing the path. Must start with `/`."
     )
     @NotNull
     private Object to;
 
     @Schema(
-        title = "If there's a conflict, have the Dropbox server try to autorename the file.",
-        description = "For example, appending (1) or (2).")
+        title = "Auto-rename on conflict",
+        description = "Default false. When true, Dropbox appends suffixes like (1) if destination exists."
+    )
     @Builder.Default
     private Property<Boolean> autorename = Property.ofValue(false);
 
@@ -157,7 +161,7 @@ DbxClientV2 createClient(RunContext runContext) throws Exception {
     @SuperBuilder
     @Getter
     public static class Output implements io.kestra.core.models.tasks.Output {
-        @Schema(title = "The metadata of the newly copied file or folder.")
+        @Schema(title = "Copied item metadata")
         private final DropboxFile file;
     }
-}
+}

src/main/java/io/kestra/plugin/dropbox/files/CreateFolder.java

@@ -48,23 +48,27 @@
         )
     }
 )
-@Schema(title = "Create a new folder in Dropbox.")
+@Schema(
+    title = "Create folder in Dropbox",
+    description = "Creates a new Dropbox folder at the resolved path. Path must start with `/`; can be read from a kestra:// URI. Fails on conflicts unless `autorename` is true (default: false)."
+)
 public class CreateFolder extends Task implements RunnableTask<CreateFolder.Output> {
 
-    @Schema(title = "Dropbox access token.")
+    @Schema(title = "Dropbox access token", description = "Token must allow writing to the target path.")
     @NotNull
     private Property<String> accessToken;
 
     @Schema(
-        title = "The path of the folder to create.",
-        description = "Can be a direct path as a string, or a Kestra internal storage URI (kestra://...) of a file containing the path."
+        title = "Folder path to create",
+        description = "Accepts a literal Dropbox path or a kestra:// URI pointing to a file that contains the path. Resolved path must start with `/`."
     )
     @NotNull
     private Object path;
 
     @Schema(
-        title = "If there's a conflict, have the Dropbox server try to autorename the file.",
-        description = "For example, appending (1) or (2).")
+        title = "Auto-rename on conflict",
+        description = "Default false. When true, Dropbox appends suffixes like (1) if the folder already exists."
+    )
     @Builder.Default
     private Property<Boolean> autorename = Property.ofValue(false);
 
@@ -143,7 +147,7 @@ DbxClientV2 createClient(RunContext runContext) throws Exception {
     @SuperBuilder
     @Getter
     public static class Output implements io.kestra.core.models.tasks.Output {
-        @Schema(title = "The metadata of the created folder.")
+        @Schema(title = "Created folder metadata")
         private final DropboxFile file;
     }
-}
+}

src/main/java/io/kestra/plugin/dropbox/files/Delete.java

@@ -47,16 +47,19 @@
         )
     }
 )
-@Schema(title = "Delete a file or folder from Dropbox.")
+@Schema(
+    title = "Delete Dropbox file or folder",
+    description = "Removes a Dropbox item at the resolved path. Path must start with `/`; can be read from a kestra:// URI. Fails if not found or token lacks delete permission."
+)
 public class Delete extends Task implements RunnableTask<Delete.Output> {
 
-    @Schema(title = "Dropbox access token.")
+    @Schema(title = "Dropbox access token", description = "Token must allow deleting the target path.")
     @NotNull
     private Property<String> accessToken;
 
     @Schema(
-        title = "The path of the file or folder to delete.",
-        description = "Can be a direct path as a string (e.g., `/my/file.txt`), or a Kestra internal storage URI (kestra://...) of a file containing the path."
+        title = "Path to delete",
+        description = "Literal Dropbox path or kestra:// URI pointing to the path content. Resolved path must start with `/`."
     )
     @NotNull
     private Object from;
@@ -133,7 +136,7 @@ DbxClientV2 createClient(RunContext runContext) throws Exception {
     @SuperBuilder
     @Getter
     public static class Output implements io.kestra.core.models.tasks.Output {
-        @Schema(title = "The metadata of the deleted file or folder.")
+        @Schema(title = "Deleted item metadata")
         private final DropboxFile file;
     }
-}
+}

src/main/java/io/kestra/plugin/dropbox/files/Download.java

@@ -66,16 +66,19 @@
         )
     }
 )
-@Schema(title = "Download a file from Dropbox.")
+@Schema(
+    title = "Download Dropbox file to storage",
+    description = "Downloads a Dropbox file and writes it to Kestra internal storage. Source path must start with `/` or be read from a kestra:// URI. Fails if the path is missing or token lacks read access."
+)
 public class Download extends Task implements RunnableTask<Download.Output> {
 
-    @Schema(title = "Dropbox access token.")
+    @Schema(title = "Dropbox access token", description = "Token must allow reading the source path.")
     @NotNull
     private Property<String> accessToken;
 
     @Schema(
-        title = "The path of the file to download.",
-        description = "Can be a direct path as a string, or a Kestra internal storage URI (kestra://...) of a file containing the path."
+        title = "Path to download",
+        description = "Literal Dropbox path or kestra:// URI containing the path. Must start with `/`."
     )
     @NotNull
     private Object from;
@@ -154,10 +157,10 @@ DbxClientV2 createClient(RunContext runContext) throws Exception {
     @SuperBuilder
     @Getter
     public static class Output implements io.kestra.core.models.tasks.Output {
-        @Schema(title = "The URI of the downloaded file in Kestra's internal storage.")
+        @Schema(title = "Downloaded file URI")
         private final URI uri;
 
-        @Schema(title = "The metadata of the downloaded file from Dropbox.")
+        @Schema(title = "Downloaded file metadata")
         private final FileMetadata metadata;
     }
-}
+}

src/main/java/io/kestra/plugin/dropbox/files/GetMetadata.java

@@ -47,21 +47,24 @@
         )
     }
 )
-@Schema(title = "Get metadata for a file or folder from Dropbox.")
+@Schema(
+    title = "Retrieve Dropbox item metadata",
+    description = "Retrieves metadata for a Dropbox file or folder. Path must start with `/` or come from a kestra:// URI. Optional media info disabled by default."
+)
 public class GetMetadata extends Task implements RunnableTask<GetMetadata.Output> {
 
-    @Schema(title = "Dropbox access token.")
+    @Schema(title = "Dropbox access token", description = "Token must allow reading the target path.")
     @NotNull
     private Property<String> accessToken;
 
     @Schema(
-        title = "The path of the file or folder to get metadata for.",
-        description = "Can be a direct path as a string, or a Kestra internal storage URI (kestra://...) of a file containing the path."
+        title = "Path to inspect",
+        description = "Literal Dropbox path or kestra:// URI containing the path. Must start with `/`."
     )
     @NotNull
     private Object path;
 
-    @Schema(title = "If true, media info will be in the response.")
+    @Schema(title = "Include media info", description = "Default false. When true, returns media info if available.")
     @Builder.Default
     private Property<Boolean> includeMediaInfo = Property.ofValue(false);
 
@@ -141,7 +144,7 @@ DbxClientV2 createClient(RunContext runContext) throws Exception {
     @SuperBuilder
     @Getter
     public static class Output implements io.kestra.core.models.tasks.Output {
-        @Schema(title = "The metadata of the file or folder.")
+        @Schema(title = "Metadata for the item")
         private final DropboxFile file;
     }
-}
+}

src/main/java/io/kestra/plugin/dropbox/files/List.java

@@ -62,32 +62,33 @@
         )
     }
 )
-@Schema(title = "List files and folders in a Dropbox directory.")
+@Schema(
+    title = "List Dropbox directory entries",
+    description = "Lists files and folders under a path (default root). Path can come from a string or kestra:// URI and should start with `/` when set. Supports recursion, limit (default 2000), and `fetchType` (default FETCH) to control memory vs storage output."
+)
 public class List extends Task implements RunnableTask<List.Output> {
 
-    @Schema(title = "Dropbox access token.")
+    @Schema(title = "Dropbox access token", description = "Token must allow listing the target path.")
     @NotNull
     private Property<String> accessToken;
 
     @Schema(
-        title = "The path to the directory to list.",
-        description = "Can be a direct path as a string, or a Kestra internal storage URI of a file containing the path."
+        title = "Directory path",
+        description = "Literal Dropbox path or kestra:// URI containing the path. Empty or null lists root. Should start with `/` when provided."
     )
     private Object from;
 
-    @Schema(title = "Whether to list files recursively in all sub-folders.")
+    @Schema(title = "Recursive listing", description = "Default false. When true, traverses sub-folders.")
     @Builder.Default
     private Property<Boolean> recursive = Property.ofValue(false);
 
-    @Schema(title = "The maximum number of files to return.")
+    @Schema(title = "Maximum entries", description = "Default 2000. Passed to Dropbox API as limit.")
     @Builder.Default
     private Property<Integer> limit = Property.ofValue(2000);
 
     @Schema(
-        title = "How to fetch the data.",
-        description = "FETCH_ONE: Returns a single row.\n" +
-            "FETCH: Returns all rows in memory.\n" +
-            "STORE: Returns all rows in a file stored in Kestra's internal storage."
+        title = "Fetch strategy",
+        description = "`FETCH_ONE`: return first entry.\n`FETCH` (default): return all entries in memory.\n`STORE`: stream entries to Kestra storage and return URI."
     )
     @Builder.Default
     private Property<FetchType> fetchType = Property.ofValue(FetchType.FETCH);
@@ -191,16 +192,16 @@ DbxClientV2 createClient(RunContext runContext) throws Exception {
     @SuperBuilder
     @Getter
     public static class Output implements io.kestra.core.models.tasks.Output {
-        @Schema(title = "The list of files and folders.", description = "Only populated if `fetchType` is `FETCH`.")
+        @Schema(title = "Directory entries", description = "Populated when `fetchType` is `FETCH`.")
         private final java.util.List<DropboxFile> rows;
 
-        @Schema(title = "The first file or folder found.", description = "Only populated if `fetchType` is `FETCH_ONE`.")
+        @Schema(title = "First entry", description = "Populated when `fetchType` is `FETCH_ONE`.")
         private final DropboxFile row;
 
-        @Schema(title = "The URI of the file in Kestra's internal storage.", description = "Only populated if `fetchType` is `STORE`.")
+        @Schema(title = "Stored entries URI", description = "Populated when `fetchType` is `STORE`.")
         private URI uri;
 
-        @Schema(title = "The number of files and folders found.")
+        @Schema(title = "Entry count")
         private final long size;
     }
-}
+}

src/main/java/io/kestra/plugin/dropbox/files/Move.java

@@ -49,34 +49,38 @@
         )
     }
 )
-@Schema(title = "Move a file or folder to a different location in Dropbox.")
+@Schema(
+    title = "Move Dropbox file or folder",
+    description = "Moves an item to a new Dropbox path. Paths must start with `/`; can be read from kestra:// URIs. Conflicts can autorename (default false). Cross-user moves require `allowOwnershipTransfer`."
+)
 public class Move extends Task implements RunnableTask<Move.Output> {
 
-    @Schema(title = "Dropbox access token.")
+    @Schema(title = "Dropbox access token", description = "Token must allow moving both source and destination paths.")
     @NotNull
     private Property<String> accessToken;
 
     @Schema(
-        title = "The path of the file or folder to be moved.",
-        description = "Can be a direct path as a string, or a Kestra internal storage URI (kestra://...) of a file containing the path."
+        title = "Source path",
+        description = "Literal Dropbox path or kestra:// URI containing the path. Must start with `/`."
     )
     @NotNull
     private Object from;
 
     @Schema(
-        title = "The destination path where the file or folder should be moved.",
-        description = "Can be a direct path as a string, or a Kestra internal storage URI (kestra://...) of a file containing the path."
+        title = "Destination path",
+        description = "Literal Dropbox path or kestra:// URI containing the path. Must start with `/`."
     )
     @NotNull
     private Object to;
 
     @Schema(
-        title = "If there's a conflict, have the Dropbox server try to autorename the file.",
-        description = "For example, appending (1) or (2).")
+        title = "Auto-rename on conflict",
+        description = "Default false. When true, Dropbox appends suffixes like (1) if destination exists."
+    )
     @Builder.Default
     private Property<Boolean> autorename = Property.ofValue(false);
 
-    @Schema(title = "Allow move to be performed even if it is between two different users.")
+    @Schema(title = "Allow ownership transfer", description = "Default false. Enables moves across different owners.")
     @Builder.Default
     private Property<Boolean> allowOwnershipTransfer = Property.ofValue(false);
 
@@ -163,7 +167,7 @@ DbxClientV2 createClient(RunContext runContext) throws Exception {
     @SuperBuilder
     @Getter
     public static class Output implements io.kestra.core.models.tasks.Output {
-        @Schema(title = "The metadata of the moved file or folder.")
+        @Schema(title = "Moved item metadata")
         private final DropboxFile file;
     }
-}
+}