From c9f1419e673474725ecb358d2800d7c51be9be9a Mon Sep 17 00:00:00 2001
From: Bolin Lin <linbolin1230@gmail.com>
Date: Wed, 21 May 2025 22:49:35 -0400
Subject: [PATCH] docs: add javadoc on S3ACl, S3BucketACl and S3Owner

---
 .../org/apache/hadoop/ozone/s3/endpoint/S3Acl.java  |  4 ++--
 .../hadoop/ozone/s3/endpoint/S3BucketAcl.java       | 13 +++++++++++--
 .../apache/hadoop/ozone/s3/endpoint/S3Owner.java    |  6 +++++-
 3 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/hadoop-ozone/s3gateway/src/main/java/org/apache/hadoop/ozone/s3/endpoint/S3Acl.java b/hadoop-ozone/s3gateway/src/main/java/org/apache/hadoop/ozone/s3/endpoint/S3Acl.java
index 63b9923947b5..ed1df4e3c671 100644
--- a/hadoop-ozone/s3gateway/src/main/java/org/apache/hadoop/ozone/s3/endpoint/S3Acl.java
+++ b/hadoop-ozone/s3gateway/src/main/java/org/apache/hadoop/ozone/s3/endpoint/S3Acl.java
@@ -33,7 +33,7 @@
 import org.slf4j.LoggerFactory;
 
 /**
- * TODO: javadoc.
+ * Represents an S3 Access Control List (ACL) that defines permissions for S3 buckets and objects.
  */
 public final class S3Acl {
   private static final Logger LOG = LoggerFactory.getLogger(S3Acl.class);
@@ -90,7 +90,7 @@ public static ACLType getType(String typeStr) {
   }
 
   /**
-   * TODO: javadoc.
+   * Represents the different types of identities that can be granted permissions in an S3 ACL.
    */
   enum ACLIdentityType {
     USER("CanonicalUser", true, "id"),
diff --git a/hadoop-ozone/s3gateway/src/main/java/org/apache/hadoop/ozone/s3/endpoint/S3BucketAcl.java b/hadoop-ozone/s3gateway/src/main/java/org/apache/hadoop/ozone/s3/endpoint/S3BucketAcl.java
index 6a1e6b802e89..78cb0ff32246 100644
--- a/hadoop-ozone/s3gateway/src/main/java/org/apache/hadoop/ozone/s3/endpoint/S3BucketAcl.java
+++ b/hadoop-ozone/s3gateway/src/main/java/org/apache/hadoop/ozone/s3/endpoint/S3BucketAcl.java
@@ -66,7 +66,11 @@ public String toString() {
   }
 
   /**
-   * TODO: javadoc.
+   * Represents an S3 Access Control List containing a collection of permission grants.
+   *
+   * This class models the AccessControlList XML element in S3 ACL responses and requests.
+   * It contains a list of Grant objects that define specific permissions granted to
+   * particular grantees (users, groups, etc.).
    */
   @XmlAccessorType(XmlAccessType.FIELD)
   @XmlRootElement(name = "AccessControlList")
@@ -100,7 +104,12 @@ public String toString() {
   }
 
   /**
-   * TODO: javadoc.
+   * Represents a single permission grant within an S3 Access Control List.
+   *
+   * This class models the Grant XML element in S3 ACL responses and requests,
+   * associating a specific permission with a grantee (the recipient of the permission).
+   * Each Grant consists of a Grantee (which identifies a user, group, or other entity)
+   * and a Permission string that specifies what access level is being granted.
    */
   @XmlAccessorType(XmlAccessType.FIELD)
   @XmlRootElement(name = "Grant")
diff --git a/hadoop-ozone/s3gateway/src/main/java/org/apache/hadoop/ozone/s3/endpoint/S3Owner.java b/hadoop-ozone/s3gateway/src/main/java/org/apache/hadoop/ozone/s3/endpoint/S3Owner.java
index d332d5824fde..bfec9038bcb0 100644
--- a/hadoop-ozone/s3gateway/src/main/java/org/apache/hadoop/ozone/s3/endpoint/S3Owner.java
+++ b/hadoop-ozone/s3gateway/src/main/java/org/apache/hadoop/ozone/s3/endpoint/S3Owner.java
@@ -23,7 +23,11 @@
 import javax.xml.bind.annotation.XmlRootElement;
 
 /**
- * TODO: javadoc.
+ * Represents an owner of S3 resources in the Ozone S3 compatibility layer.
+ *
+ * This class models the Owner XML element in S3 responses, containing both a unique ID
+ * and a display name for the owner of buckets and objects.
+ *
  */
 @XmlAccessorType(XmlAccessType.FIELD)
 @XmlRootElement(name = "Owner")