From e5068c43b0cb7aa5d4a134ca2a57aca19d39e77c Mon Sep 17 00:00:00 2001
From: Francesco Cozzuto <francesco.cozzuto@gmail.com>
Date: Mon, 1 Dec 2025 14:42:25 +0100
Subject: [PATCH] Add comments to s3.h

---
 s3.c | 10 +++++-----
 s3.h | 33 ++++++++++++++++++++++++---------
 2 files changed, 29 insertions(+), 14 deletions(-)

diff --git a/s3.c b/s3.c
index f07a6ee..d64275a 100644
--- a/s3.c
+++ b/s3.c
@@ -541,7 +541,7 @@ int s3_presign_url(
 
     struct tm unpacked_now;
     if (unpack_time(now, &unpacked_now))
-        return -1; // TODO
+        return S3_OTHER_ERROR;
 
     char date_buf_0[sizeof("YYYYMMDD")];
     char date_buf_1[sizeof("YYYYMMDDthhmmssz")];
@@ -549,7 +549,7 @@ int s3_presign_url(
     int ret = strftime(date_buf_0, sizeof(date_buf_0),
         "%Y%m%d", &unpacked_now);
     if (ret != sizeof(date_buf_0)-1)
-        return -1; // TODO
+        return S3_OTHER_ERROR;
     S3_String yyyymmdd = {
         date_buf_0,
         sizeof(date_buf_0)-1
@@ -558,7 +558,7 @@ int s3_presign_url(
     ret = strftime(date_buf_1, sizeof(date_buf_1),
         "%Y%m%dT%H%M%SZ", &unpacked_now);
     if (ret != sizeof(date_buf_1)-1)
-        return -1; // TODO
+        return S3_OTHER_ERROR;
     S3_String yyyymmddthhmmssz = {
         date_buf_1,
         sizeof(date_buf_1)-1
@@ -567,14 +567,14 @@ int s3_presign_url(
     char hash_buf[32];
     if (payload.len > 0) {
         if (sha256(payload.ptr, payload.len, hash_buf) < 0)
-            return -1;
+            return S3_LIB_ERROR;
     }
     S3_String hash = { hash_buf, sizeof(hash_buf) };
 
     char expire_buf[11];
     ret = snprintf(expire_buf, sizeof(expire_buf), "%d", expire);
     if (ret < 0 || ret >= (int) sizeof(expire_buf))
-        return -1;
+        return S3_OTHER_ERROR;
     S3_String expire_str = { expire_buf, ret };
 
     for (int i = 0; i < 2; i++) {
diff --git a/s3.h b/s3.h
index cdc9026..5ed4a51 100644
--- a/s3.h
+++ b/s3.h
@@ -3,18 +3,33 @@
 
 #include <time.h>
 
-#define S3_S(X) (S3_String) { (X), sizeof(X)-1 }
-
-enum {
-    S3_OUT_OF_MEMORY = -1,
-    S3_LIB_ERROR     = -2,
-};
-
 typedef struct {
     char *ptr;
     int   len;
 } S3_String;
 
+// Utility to translate string literals to S3_Strings
+#define S3_S(X) (S3_String) { (X), sizeof(X)-1 }
+
+enum {
+    S3_OUT_OF_MEMORY = -1,
+    S3_LIB_ERROR     = -2,
+    S3_OTHER_ERROR   = -3,
+};
+
+// Writes the presigned URL in the dst buffer and
+// returns the number of bytes written. No more than
+// "cap" bytes are ever written. On error, a negative
+// status code is returned:
+//
+//   S3_OUT_OF_MEMORY
+//     An allocation failed or the output buffer is too small
+//
+//   S3_LIB_ERROR
+//     The underlying crypto library failed
+//
+//   S3_OTHER_ERROR
+//     Some other error
 int s3_presign_url(
     S3_String bucket,
     S3_String object,
@@ -27,7 +42,7 @@ int s3_presign_url(
     S3_String service,
     S3_String host,
     time_t    now,
-    char *dst,
-    int   cap);
+    char*     dst,
+    int       cap);
 
 #endif // S3_INCLUDED