From 6f51637da76cd937dbaff89ed35f26db68a95d25 Mon Sep 17 00:00:00 2001
From: Aditya Manthramurthy <aditya.mmy@gmail.com>
Date: Thu, 28 Sep 2023 12:15:48 -0700
Subject: [PATCH] Add doc for list_objects

---
 Cargo.toml       |  2 +-
 src/s3/args.rs   | 26 +++++++++++++++++++-------
 src/s3/client.rs |  3 +++
 3 files changed, 23 insertions(+), 8 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index 2b78cd8..e60073f 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "minio"
-version = "0.1.0"
+version = "0.2.0-alpha"
 edition = "2021"
 authors = ["MinIO Dev Team <dev@min.io>"]
 description = "MinIO SDK for Amazon S3 compatible object storage access"
diff --git a/src/s3/args.rs b/src/s3/args.rs
index d67dfb4..7173a99 100644
--- a/src/s3/args.rs
+++ b/src/s3/args.rs
@@ -1116,21 +1116,33 @@ pub struct ListObjectsArgs<'a> {
     pub extra_headers: Option<&'a Multimap>,
     pub extra_query_params: Option<&'a Multimap>,
     pub region: Option<&'a str>,
+    /// Specifies the bucket name on which listing is to be performed.
     pub bucket: &'a str,
+    /// Delimiter to roll up common prefixes on.
     pub delimiter: Option<&'a str>,
     pub use_url_encoding_type: bool,
-    pub marker: Option<&'a str>,      // only for ListObjectsV1.
-    pub start_after: Option<&'a str>, // only for ListObjectsV2.
-    pub key_marker: Option<&'a str>,  // only for GetObjectVersions.
+    /// Used only with ListObjectsV1.
+    pub marker: Option<&'a str>,
+    /// Used only with ListObjectsV2
+    pub start_after: Option<&'a str>,
+    /// Used only with GetObjectVersions.
+    pub key_marker: Option<&'a str>,
     pub max_keys: Option<u16>,
     pub prefix: Option<&'a str>,
-    pub continuation_token: Option<&'a str>, // only for ListObjectsV2.
-    pub fetch_owner: bool,                   // only for ListObjectsV2.
-    pub version_id_marker: Option<&'a str>,  // only for GetObjectVersions.
-    pub include_user_metadata: bool,         // MinIO extension for ListObjectsV2.
+    /// Used only with ListObjectsV2.
+    pub continuation_token: Option<&'a str>,
+    /// Used only with ListObjectsV2.
+    pub fetch_owner: bool,
+    /// Used only with GetObjectVersions.
+    pub version_id_marker: Option<&'a str>,
+    /// MinIO extension for ListObjectsV2.
+    pub include_user_metadata: bool,
     pub recursive: bool,
+    /// Set this to use ListObjectsV1. Defaults to false.
     pub use_api_v1: bool,
+    /// Set this to include versions.
     pub include_versions: bool,
+    /// A callback function to process results of object listing.
     pub result_fn: &'a dyn Fn(Vec<Item>) -> bool,
 }
 
diff --git a/src/s3/client.rs b/src/s3/client.rs
index e26994a..ecb2374 100644
--- a/src/s3/client.rs
+++ b/src/s3/client.rs
@@ -2750,6 +2750,9 @@ impl Client {
         })
     }
 
+    /// List objects with version information optionally. `results_fn` callback
+    /// function is repeatedly called with object information and returning
+    /// false from the callback stops further listing.
     pub async fn list_objects(&self, args: &ListObjectsArgs<'_>) -> Result<(), Error> {
         let mut lov1_args = ListObjectsV1Args::new(args.bucket)?;
         lov1_args.extra_headers = args.extra_headers;