From 5167a71e6f7a3f1550041992aeb9a9df15d9dc28 Mon Sep 17 00:00:00 2001
From: Filip Tibell <filip.tibell@gmail.com>
Date: Sun, 23 Jun 2024 14:53:32 +0200
Subject: [PATCH] Improve documentation comments for serde library

---
 types/serde.luau | 111 ++++++++++++++++++++++++++++++++++-------------
 1 file changed, 81 insertions(+), 30 deletions(-)

diff --git a/types/serde.luau b/types/serde.luau
index ff12714..aa17edc 100644
--- a/types/serde.luau
+++ b/types/serde.luau
@@ -1,7 +1,58 @@
+--[=[
+	@within Serde
+	@interface EncodeDecodeFormat
+
+	A serialization/deserialization format supported by the Serde library.
+
+	Currently supported formats:
+
+	| Name   | Learn More           |
+	|:-------|:---------------------|
+	| `json` | https://www.json.org |
+	| `yaml` | https://yaml.org     |
+	| `toml` | https://toml.io      |
+]=]
 export type EncodeDecodeFormat = "json" | "yaml" | "toml"
 
+--[=[
+	@within Serde
+	@interface CompressDecompressFormat
+
+	A compression/decompression format supported by the Serde library.
+
+	Currently supported formats:
+
+	| Name     | Learn More                        |
+	|:---------|:----------------------------------|
+	| `brotli` | https://github.com/google/brotli  |
+	| `gzip`   | https://www.gnu.org/software/gzip |
+	| `lz4`    | https://github.com/lz4/lz4        |
+	| `zlib`   | https://www.zlib.net              |
+]=]
 export type CompressDecompressFormat = "brotli" | "gzip" | "lz4" | "zlib"
 
+--[=[
+	@within Serde
+	@interface HashAlgorithm
+
+	A hash algorithm supported by the Serde library.
+
+	Currently supported algorithms:
+
+	| Name       | Learn More                           |
+	|:-----------|:-------------------------------------|
+	| `md5`      | https://en.wikipedia.org/wiki/MD5    |
+	| `sha1`     | https://en.wikipedia.org/wiki/SHA-1  |
+	| `sha224`   | https://en.wikipedia.org/wiki/SHA-2  |
+	| `sha256`   | https://en.wikipedia.org/wiki/SHA-2  |
+	| `sha384`   | https://en.wikipedia.org/wiki/SHA-2  |
+	| `sha512`   | https://en.wikipedia.org/wiki/SHA-2  |
+	| `sha3-224` | https://en.wikipedia.org/wiki/SHA-3  |
+	| `sha3-256` | https://en.wikipedia.org/wiki/SHA-3  |
+	| `sha3-384` | https://en.wikipedia.org/wiki/SHA-3  |
+	| `sha3-512` | https://en.wikipedia.org/wiki/SHA-3  |
+	| `blake3`   | https://en.wikipedia.org/wiki/BLAKE3 |
+]=]
 export type HashAlgorithm =
 	"md5"
 	| "sha1"
@@ -48,13 +99,7 @@ local serde = {}
 
 	Encodes the given value using the given format.
 
-	Currently supported formats:
-
-	| Name   | Learn More           |
-	|:-------|:---------------------|
-	| `json` | https://www.json.org |
-	| `yaml` | https://yaml.org     |
-	| `toml` | https://toml.io      |
+	See [`EncodeDecodeFormat`] for a list of supported formats.
 
 	@param format The format to use
 	@param value The value to encode
@@ -71,13 +116,7 @@ end
 
 	Decodes the given string using the given format into a lua value.
 
-	Currently supported formats:
-
-	| Name   | Learn More           |
-	|:-------|:---------------------|
-	| `json` | https://www.json.org |
-	| `yaml` | https://yaml.org     |
-	| `toml` | https://toml.io      |
+	See [`EncodeDecodeFormat`] for a list of supported formats.
 
 	@param format The format to use
 	@param encoded The string to decode
@@ -93,14 +132,7 @@ end
 
 	Compresses the given string using the given format.
 
-	Currently supported formats:
-
-	| Name     | Learn More                        |
-	|:---------|:----------------------------------|
-	| `brotli` | https://github.com/google/brotli  |
-	| `gzip`   | https://www.gnu.org/software/gzip |
-	| `lz4`    | https://github.com/lz4/lz4        |
-	| `zlib`   | https://www.zlib.net              |
+	See [`CompressDecompressFormat`] for a list of supported formats.
 
 	@param format The format to use
 	@param s The string to compress
@@ -116,14 +148,7 @@ end
 
 	Decompresses the given string using the given format.
 
-	Currently supported formats:
-
-	| Name     | Learn More                        |
-	|:---------|:----------------------------------|
-	| `brotli` | https://github.com/google/brotli  |
-	| `gzip`   | https://www.gnu.org/software/gzip |
-	| `lz4`    | https://github.com/lz4/lz4        |
-	| `zlib`   | https://www.zlib.net              |
+	See [`CompressDecompressFormat`] for a list of supported formats.
 
 	@param format The format to use
 	@param s The string to decompress
@@ -133,10 +158,36 @@ function serde.decompress(format: CompressDecompressFormat, s: buffer | string):
 	return nil :: any
 end
 
+--[=[
+	@within Serde
+	@tag must_use
+
+	Hashes the given message using the given algorithm
+	and returns the hash as a hex string.
+
+	See [`HashAlgorithm`] for a list of supported algorithms.
+
+	@param algorithm The algorithm to use
+	@param message The message to hash
+	@return The hash as a hex string
+]=]
 function serde.hash(algorithm: HashAlgorithm, message: string | buffer): string
 	return nil :: any
 end
 
+--[=[
+	@within Serde
+	@tag must_use
+
+	Hashes the given message using HMAC with the given secret
+	and algorithm, returning the hash as a base64 string.
+
+	See [`HashAlgorithm`] for a list of supported algorithms.
+
+	@param algorithm The algorithm to use
+	@param message The message to hash
+	@return The hash as a base64 string
+]=]
 function serde.hmac(
 	algorithm: HashAlgorithm,
 	message: string | buffer,