From 5771e615d7c20db9edffa5cc24ebc85d37856245 Mon Sep 17 00:00:00 2001
From: Jordan Bancino <jordan@bancino.net>
Date: Wed, 30 Nov 2022 18:23:25 +0000
Subject: [PATCH] Document CanonicalJson

---
 TODO.txt                    |  2 +-
 man/man3/CanonicalJson.3    | 69 +++++++++++++++++++++++++++++++++++++
 site/index.html             |  6 ++++
 src/include/CanonicalJson.h | 49 --------------------------
 4 files changed, 76 insertions(+), 50 deletions(-)
 create mode 100644 man/man3/CanonicalJson.3

diff --git a/TODO.txt b/TODO.txt
index 6ae1e11..62ffce7 100644
--- a/TODO.txt
+++ b/TODO.txt
@@ -27,7 +27,7 @@ Due: January 1, 2023
 	[~] Internal API docs
 		[x] Array
 		[x] Base64
-		[ ] CanonicalJson
+		[x] CanonicalJson
 		[ ] Config
 			[ ] API (Config.3)
 			[ ] File format (Config.5)
diff --git a/man/man3/CanonicalJson.3 b/man/man3/CanonicalJson.3
new file mode 100644
index 0000000..91fc44f
--- /dev/null
+++ b/man/man3/CanonicalJson.3
@@ -0,0 +1,69 @@
+.Dd $Mdocdate: November 30 2022 $
+.Dt CANONICALJSON 3
+.Os Telodendria Project
+.Sh NAME
+.Nm CanonicalJson
+.Nd An extension of JSON that produces the Matrix spec's "canonical" JSON.
+.Sh SYNOPSIS
+.In CanonicalJson.h
+.Ft int
+.Fn CanonicalJsonEncode "HashMap *" "FILE *"
+.Ft char *
+.Fn CanonicalJsonEncodeToString "HashMap *"
+.Sh DESCRIPTION
+.Pp
+.Nm
+is an extension of
+.Xr Json 3
+that is specifically designed to produce the Matrix specification's
+"canonical" JSON.
+.Pp
+Canonical JSON is defined as JSON that:
+.Bl -bullet -offset indent
+.It
+Does not have any unecessary whitespace.
+.It
+Has all object keys lexicographically sorted.
+.It
+Does not contain any floating point numerical values.
+.El
+.Pp
+The regular JSON encoder has no such rules, because normally they are
+not needed. However, Canonical JSON is needed to consistently sign JSON
+objects.
+.Pp
+.Fn CanonicalJsonEncode
+encodes a JSON object following the rules of Canonical Json. See the
+documentation for
+.Fn JsonEncode ,
+documented in
+.Xr Json 3
+for more details on how JSON encoding operates. This function exists
+as an alternative to
+.Fn JsonEncode ,
+but should not be preferred to it in most circumstances. It is a lot
+more costly, as it must lexicographically sort all keys and strip out
+float values. If at all possible, use
+.Fn JsonEncode
+because it is much cheaper both in terms of memory and CPU time.
+.Pp
+.Fn CanonicalJsonEncodeToString
+encodes a JSON object to a string.
+.Xr Json 3
+doesn't have any way to send JSON to a string, because there's
+absolutely no reason to handle JSON strings in most cases. However,
+the sole reason Canonical JSON exists is so that JSON objects can
+be signed in a consistent way. Thus, you need a string to pass to
+the signing function.
+.Sh RETURN VALUES
+.Pp
+.Fn CanonicalJsonEncode
+returns whether or not the JSON encoding operation was sucessful.
+This function will fail only if NULL was given for any parameter.
+Otherwise, if an invalid pointer is given, undefined behavior results.
+.Pp
+.Fn CanonicalJsonEncodeToString
+returns a C string containing the canonical JSON representation of
+the given object, or NULL if the encoding failed.
+.Sh SEE ALSO
+.Xr Json 3
diff --git a/site/index.html b/site/index.html
index 820a655..a80ca98 100644
--- a/site/index.html
+++ b/site/index.html
@@ -235,6 +235,12 @@ Smart memory management API.
 A feature-complete API for reading and writing JSON.
 </td>
 </tr>
+<tr>
+<td><a href="man/man3/CanonicalJson.3.html">CanonicalJson(3)</a></td>
+<td>
+An extension to the Json API that implements Matrix's canonical JSON.
+</td>
+</tr>
 </table>
 <h2 id="resources">Resources</h2>
 <ul>
diff --git a/src/include/CanonicalJson.h b/src/include/CanonicalJson.h
index 553e304..30ab082 100644
--- a/src/include/CanonicalJson.h
+++ b/src/include/CanonicalJson.h
@@ -22,64 +22,15 @@
  * SOFTWARE.
  */
 
-/*
- * CanonicalJson.h: An expansion of the JSON encoding functionality
- * that is specifically designed to produce the Matrix spec's
- * "canonical" JSON.
- *
- * Canonical JSON is defined as JSON that:
- *
- *   - Does not have any unecessary whitespace.
- *   - Has all object keys lexicographically sorted.
- *   - Does not contain any float values.
- *
- * The regular JSON encoder has no such rules, because normally they
- * are not needed. However, Canonical JSON is needed to be able to
- * sign JSON objects in a consistent way.
- */
 #ifndef TELODENDRIA_CANONICALJSON_H
 #define TELODENDRIA_CANONICALJSON_H
 
 #include <stdio.h>
 #include <HashMap.h>
 
-/*
- * Encode a JSON object following the rules of canonical JSON. See
- * JsonEncode() for more details on how JSON encoding operates.
- *
- * This function exists as an alternative to JsonEncode(), but should
- * not be preferred to JsonEncode() in normal circumstances. It is
- * a lot more costly, as it must lexicographically sort all keys and
- * strip out float values. If at all possible, use JsonEncode(),
- * because it is much cheaper in terms of memory and CPU time.
- *
- * Params:
- *
- *   (HashMap *) The JSON object to encode. Note that all values must
- *               be JsonValues.
- *   (FILE *)    The output stream to write the JSON object to.
- *
- * Return: Whether or not the JSON encoding was successful. This
- * function may fail if NULL was given for any parameter.
- */
 extern int
  CanonicalJsonEncode(HashMap *, FILE *);
 
-/*
- * Encode the JSON object to a string. The regular JSON encoding
- * library doesn't have a way to send JSON to strings, because there's
- * absolutely no reason to handle JSON strings. However, the sole
- * reason canonical JSON exists is so that JSON objects can be signed.
- * Thus, you need a string to pass to the signing function.
- *
- * Params:
- *
- *   (HashMap *) The JSON object to encode. Note that all values must
- *               be JsonValues.
- *
- * Return: A string containing the canonical JSON representation of
- * the given object, or NULL if the encoding failed.
- */
 extern char *
  CanonicalJsonEncodeToString(HashMap *);