From 1449e966ab839a40b096c3d050373e27061af39b Mon Sep 17 00:00:00 2001
From: apio <blobs.trading@gmail.com>
Date: Wed, 23 Aug 2023 13:34:14 +0200
Subject: [PATCH] libluna: Document Base64.h

---
 libluna/include/luna/Base64.h | 48 +++++++++++++++++++++++++++++++++++
 libluna/src/Base64.cpp        | 11 +++++++-
 2 files changed, 58 insertions(+), 1 deletion(-)

diff --git a/libluna/include/luna/Base64.h b/libluna/include/luna/Base64.h
index 3efe79b8..192cd588 100644
--- a/libluna/include/luna/Base64.h
+++ b/libluna/include/luna/Base64.h
@@ -1,13 +1,61 @@
+/**
+ * @file Base64.h
+ * @author apio (cloudapio.eu)
+ * @brief Base64 encoding and decoding.
+ *
+ * @copyright Copyright (c) 2023, the Luna authors.
+ *
+ */
+
 #pragma once
 #include <luna/Buffer.h>
 #include <luna/String.h>
 
 namespace Base64
 {
+    /**
+     * @brief Encode a string into Base64.
+     *
+     * @param data The string to encode.
+     * @return Result<String> An error, or the resulting Base64 string.
+     */
     Result<String> encode(StringView data);
+
+    /**
+     * @brief Encode a slice of data into Base64.
+     *
+     * @param data The data to encode.
+     * @return Result<String> An error, or the resulting Base64 string.
+     */
     Result<String> encode(Slice<const u8> data);
+
+    /**
+     * @brief Encode a buffer into Base64.
+     *
+     * @param data The buffer to encode.
+     * @return Result<String> An error, or the resulting Base64 string.
+     */
     Result<String> encode(const Buffer& data);
 
+    /**
+     * @brief Decode a Base64 string.
+     *
+     * @param data The string to decode.
+     * @param allow_garbage_chars Whether to skip non-Base64 characters instead of returning an error.
+     * @return Result<Buffer> An error, or the raw decoded data.
+     */
     Result<Buffer> decode(StringView data, bool allow_garbage_chars = false);
+
+    /**
+     * @brief Decode a Base64 string, returning a string instead of raw data.
+     *
+     * Note that decoded Base64 may be anything; invalid UTF-8, null characters in the middle of data, etc...
+     * For this reason it is not recommended to use this function unless you're sure that what is decoded will be a
+     * valid string (so, don't use this with untrusted user input).
+     *
+     * @param data The string to decode.
+     * @param allow_garbage_chars Whether to skip non-Base64 characters instead of returning an error.
+     * @return Result<String> An error, or the decoded string.
+     */
     Result<String> decode_string(StringView data, bool allow_garbage_chars = false);
 }
diff --git a/libluna/src/Base64.cpp b/libluna/src/Base64.cpp
index 203bccd6..64a74e0d 100644
--- a/libluna/src/Base64.cpp
+++ b/libluna/src/Base64.cpp
@@ -1,3 +1,12 @@
+/**
+ * @file Base64.cpp
+ * @author apio (cloudapio.eu)
+ * @brief Base64 encoding and decoding.
+ *
+ * @copyright Copyright (c) 2023, the Luna authors.
+ *
+ */
+
 #include <luna/Base64.h>
 #include <luna/CType.h>
 #include <luna/DebugLog.h>
@@ -152,6 +161,6 @@ namespace Base64
         u8 nul_byte = '\0';
         TRY(buf.append_data(&nul_byte, 1));
 
-        return String { (char*)buf.release_data() };
+        return String { (char*)buf.release_data(), buf.size() };
     }
 }