From e0a77fcb1ad7d6b719a7c091b3f1b60095a10214 Mon Sep 17 00:00:00 2001
From: iTrooz <hey@itrooz.fr>
Date: Sat, 28 Jun 2025 18:16:42 +0200
Subject: [PATCH] Add documentation for copy_object (#172)

* Add documentation about source/destination of copy_object
* update copy object documentation

---------

Co-authored-by: Henk-Jan Lebbink <henkjan.lebbink@gmail.com>
---
 src/s3/builders/copy_object.rs |  6 +++++
 src/s3/client/copy_object.rs   | 41 +++++++++++++++++++++++++++++++---
 src/s3/response/copy_object.rs |  4 ++--
 3 files changed, 46 insertions(+), 5 deletions(-)

diff --git a/src/s3/builders/copy_object.rs b/src/s3/builders/copy_object.rs
index 47ff81c..60c6bdd 100644
--- a/src/s3/builders/copy_object.rs
+++ b/src/s3/builders/copy_object.rs
@@ -405,6 +405,8 @@ impl CopyObject {
         self.legal_hold = legal_hold;
         self
     }
+
+    /// Sets the source for the copy operation.
     pub fn source(mut self, source: CopySource) -> Self {
         self.source = source;
         self
@@ -418,6 +420,10 @@ impl CopyObject {
         self
     }
 
+    /// Sends the copy object request.
+    ///
+    /// Functionally related to the [S3Api::send()](crate::s3::types::S3Api::send) method, but
+    /// specifically tailored for the `CopyObject` operation.
     pub async fn send(self) -> Result<CopyObjectResponse, Error> {
         {
             if let Some(v) = &self.sse {
diff --git a/src/s3/client/copy_object.rs b/src/s3/client/copy_object.rs
index 4b8d0f1..a34b906 100644
--- a/src/s3/client/copy_object.rs
+++ b/src/s3/client/copy_object.rs
@@ -30,7 +30,7 @@ impl Client {
     ///
     /// ```no_run
     /// use minio::s3::Client;
-    /// use minio::s3::response::{UploadPartCopyResponse};
+    /// use minio::s3::response::UploadPartCopyResponse;
     /// use minio::s3::segmented_bytes::SegmentedBytes;
     /// use minio::s3::types::S3Api;
     /// use minio::s3::response::a_response_traits::HasObject;
@@ -65,8 +65,43 @@ impl Client {
         CopyObjectInternal::new(self.clone(), bucket.into(), object.into())
     }
 
-    /// copy object is a higher-level API that calls [stat_object](Client::stat_object) and based on the results calls
-    /// [compose_object](Client::compose_object) to copy the object.
+    /// Create a CopyObject request builder.
+    /// See [CopyObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html) S3 API
+    ///
+    /// To execute the copy operation, call [`CopyObject::send()`](crate::s3::types::S3Api::send),
+    /// which returns a [`Result`] containing a [`CopyObjectResponse`](crate::s3::response::CopyObjectResponse).
+    ///
+    /// The destination of the copy is specified via the `bucket` and `object` parameters of this function.
+    /// To specify the source object to be copied, call `.source(...)` on the returned [`CopyObject`] builder.
+    ///
+    /// Internally, this function first performs a [`stat_object`](Client::stat_object) call
+    /// to retrieve metadata about the source object. It then constructs a
+    /// [`compose_object`](Client::compose_object) request to perform the actual copy.
+    ///
+    /// # Arguments
+    ///
+    /// - `bucket`: The name of the destination bucket.
+    /// - `object`: The key (name) of the destination object.
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// use minio::s3::Client;
+    /// use minio::s3::response::CopyObjectResponse;
+    /// use minio::s3::builders::CopySource;
+    /// use minio::s3::types::S3Api;
+    ///
+    /// #[tokio::main]
+    /// async fn main() {
+    /// use minio::s3::response::a_response_traits::HasVersion;
+    /// let client: Client = Default::default(); // configure your client here
+    ///     let resp: CopyObjectResponse = client
+    ///         .copy_object("bucket-name-dst", "object-name-dst")
+    ///         .source(CopySource::new("bucket-name-src", "object-name-src").unwrap())
+    ///         .send().await.unwrap();
+    ///     println!("copied the file from src to dst. New version: {:?}", resp.version_id());
+    /// }
+    /// ```
     pub fn copy_object<S1: Into<String>, S2: Into<String>>(
         &self,
         bucket: S1,
diff --git a/src/s3/response/copy_object.rs b/src/s3/response/copy_object.rs
index 31ef39c..e885172 100644
--- a/src/s3/response/copy_object.rs
+++ b/src/s3/response/copy_object.rs
@@ -47,10 +47,10 @@ pub type UploadPartCopyResponse = S3Response2;
 /// Internal response type for copy operations
 pub type CopyObjectInternalResponse = S3Response2;
 
-/// Represents the response of the `copy_object` API call.
+/// Represents the response of the [copy_object()](crate::s3::client::Client::copy_object) API call.
 /// This struct contains metadata and information about the object being copied.
 pub type CopyObjectResponse = S3Response2;
 
-/// Represents the response of the `[compose_object()](crate::s3::client::Client::compose_object) API call.
+/// Represents the response of the [compose_object()](crate::s3::client::Client::compose_object) API call.
 /// This struct contains metadata and information about the composed object.
 pub type ComposeObjectResponse = S3Response2;