Move Base64 documentation to man page.

docs/Array.3

@@ -1,4 +1,4 @@
-.Dd $Mdocdate: September 25 2022 $
+.Dd $Mdocdate: September 27 2022 $
 .Dt ARRAY 3
 .Os Telodendria Project
 .Sh NAME
@@ -87,7 +87,9 @@ the opposite: the second element should appear after the first in the array.
 is used to get the element at the specified index.
 .Sh RETURN VALUES
 .Fn ArrayCreate
-returns a pointer on the heap to a newly allocated array structure.
+returns a pointer on the heap to a newly allocated array structure, or
+.Dv NULL
+if the allocation fails.
 .Pp
 .Fn ArrayGet
 and

docs/Base64.3

@@ -0,0 +1,81 @@
+.Dd $Mdocdate: September 27 2022 $
+.Dt BASE64 3
+.Os Telodendria Project
+.Sh NAME
+.Nm Base64
+.Nd A simple base64 encoder/decoder with "unpadded base64" support.
+.Sh SYNOPSIS
+.In Base64.h
+.Ft size_t
+.Fn Base64EncodedSize "size_t"
+.Ft size_t
+.Fn Base64DecodedSize "const char *" "size_t"
+.Ft char *
+.Fn Base64Encode "const char *" "size_t"
+.Ft char *
+.Fn Base64Decode "const char *" "size_t"
+.Ft void
+.Fn Base64Unpad "char *" "size_t"
+.Ft int
+.Fn Base64Pad "char **" "size_t"
+.Sh DESCRIPTION
+This is an efficient yet simple base64 encoding and decoding
+library that supports regular base64, as well as the Matrix
+specification's extension to base64, called "unpadded base64."
+.Nm provides the ability to convert between the two, instead of
+just implementing "unpadded base64."
+.Pp
+.Fn Base64EncodedSize
+and
+.Fn Base64DecodedSize
+compute the amount of characters needed to store an encoded or
+decoded message, respectively. Both functions take the size of
+the message being encoded or decoded, but
+.Fn Base64DecodedSize
+also takes a pointer to an encoded string, because a few bytes of
+the string need to be read in order to compute the size.
+.Pp
+.Fn Base64Encode
+and
+.Fn Base64Decode
+do the actual work of encoding and decoding base64 data. They both
+take a string and its length.
+.Pp
+.Fn Base64Unpad
+and
+.Fn Base64Pad
+are used to implement Matrix unpadded base64.
+.Fn Base64Unpad
+takes a valid base64 string and strips off the trailing equal signs,
+as per the specification.
+.Fn Base64Pad
+does the opposite; it takes an unpadded base64 input string, and pads
+it with equal signs as necessary, so that it can be properly decoded
+with
+.Fn Base64Decode
+if necessary. However, the Matrix specification envisons unpadded base64
+as opaque; that is, once it's encoded, it never needs to be decoded.
+In practice, a homeserver might need to decode an unpadded base64 string.
+.Sh RETURN VALUES
+.Fn Base64EncodedSize
+and
+.Fn Base64DecodedSize
+simply return unsigned integers representing a number of bytes generated
+from a simple computation.
+.Pp
+.Fn Base64Encode
+and
+.Fn Base64Decode
+return pointers to new strings, allocated on the heap, or
+.Dv NULL
+if a heap allocation fails. These pointers must be
+.Xr free 3 -ed
+at some point when they are no longer needed.
+.Pp
+.Fn Base64Unpad
+modifies the passed string in-place. It thus has no return value, because
+it cannot fail. If the passed pointer is invalid, the behavior is undefined.
+.Fn Base64Pad
+returns a boolean value indicating whether the pad operation was successful.
+In practice, this function will only fail if a bigger string is necessary, but
+could not be automatically allocated on the heap.

docs/telodendria.7

@@ -1,4 +1,4 @@
-.Dd $Mdocdate: September 23 2022 $
+.Dd $Mdocdate: September 27 2022 $
 .Dt TELODENDRIA 7
 .Os Telodendria Project
 .Sh NAME
@@ -88,10 +88,8 @@ up the data directory and you're good to go.
 .Sh PROJECT GOALS
 The goals of this project are generally divided into user goals and developer
 goals, depending on who they impact the most. This isn't an exaustive list
-of
+of the project's goals, but it is a list of things that I want to prioritize,
-.Nm 's
+because other server implementations lack them.
-goals, but it is a list of things that I want to prioritize, because other
-server implementations lack them.
 .sp
 The user goals are as follows:
 .Bl -bullet

src/include/Base64.h

@@ -22,133 +22,26 @@
  * SOFTWARE.
  */
 
-/*
- * Base64.h: An efficient base64 encoder and decoder that supports
- * both regular base64, and the Matrix spec's "unpadded base64."
- */
 #ifndef TELODENDRIA_BASE64_H
 #define TELODENDRIA_BASE64_H
 
 #include <stddef.h>
 
-/*
- * Compute the encoded size, including padding, of an input with the
- * provided size.
- *
- * Params:
- *
- *   (size_t) The size of the input data to be encoded.
- *
- * Return: The size of the string needed to hold the data in its
- * encoded form. Note that base64 is not compression; base64 strings
- * are actually 25% larger than the unencoded input.
- */
 extern size_t
  Base64EncodedSize(size_t);
 
-/*
- * Compute the decoded size of the provide base64 input and length.
- *
- * Note that both the size and the actual base64 string itself is
- * needed for this computation, unlike Base64EncodedSize(). This is
- * because base64 strings are padded, and that padding is used in the
- * calculations.
- *
- * Params:
- *
- *   (const char *) A padded base64 string. If you are dealing with
- *                  potentially user-provided base64, you should call
- *                  Base64Pad() on it to normalize it before computing
- *                  the decoded size.
- *   (size_t) The length of the base64 string. Instead of scanning the
- *            string for a null terminator, and then working backwards,
- *            the length of the string must be passed here.
- *
- * Return: The number of bytes that can be decoded from this base64
- * string. Note that this will be smaller than the length of the base64
- * string because base64 is larger than the unencoded form.
- */
 extern size_t
  Base64DecodedSize(const char *, size_t);
 
-/*
- * Copy the given input string to a new string, base64 encoding it in
- * the process. This function will produce standard padded base64. If
- * you want unpadded base64, call Base64Unpad() on the return value
- * of this function.
- *
- * Params:
- *
- *   (const char *) The raw, unencoded input to be encoded as base64.
- *   (size_t)       The length of the unencoded input string.
- *
- * Return: A new string, allocated on the heap, that holds the base64
- * representation of the input. This string must be free()-ed when it
- * is no longer needed. If the allocation of the proper size fails,
- * or the input is inaccessible, then this function will return NULL.
- */
 extern char *
  Base64Encode(const char *, size_t);
 
-/*
- * Decode a standard padded base64 string. This function expects that
- * the input will be padded, so if you are recieving untrusted input,
- * you should run Base64Pad() on it before attempting to decode it.
- *
- * Params:
- *
- *   (const char *) The base64 string to decode.
- *   (size_t)       The length of the base64 string to decode.
- *
- * Return: A new string, allocated on the heap, that contains the
- * decoded string, or NULL if a decoding error occurred.
- */
 extern char *
  Base64Decode(const char *, size_t);
 
-/*
- * Remove the padding from a base64 string. This is to implement the
- * Matrix spec's "unpadded base64" functionality. When base64 strings
- * are sent to other servers and clients, their padding must be
- * stripped.
- *
- * Params:
- *
- *   (char *) The base64 string to remove padding from. Note that
- *            this string is modified in place.
- *   (size_t) The length of the provided base64 string.
- *
- */
 extern void
  Base64Unpad(char *, size_t);
 
-/*
- * Pad a base64 string in place. This is to implement the Matrix spec's
- * "unpadded base64." As we will most likely be getting unpadded base64
- * from clients and other servers, we should pad it before attempting
- * to decode it.
- *
- * I technically could have just had the decoder accept unpadded as
- * well as padded strings, but Matrix is the only thing I know of that
- * actually makes "unpadded" base64 a thing, so I thought it best to
- * make it clear in this library that unpadded base64 is an extension,
- * not the norm.
- *
- * Params:
- *
- *   (char **) A pointer to a base64 string pointer. The reason we
- *             take a pointer pointer is because the string may need
- *             to be reallocated, as characters may be added to the
- *             end of it. If the string is reallocated, then the
- *             passed pointer must be updated. If the string is not
- *             reallocated, the original pointer is not touched.
- *   (size_t)  The length of the given base64 string.
- *
- * Return: Whether or not the pad operation was successful. This
- * function will fail if a larger string cannot be allocated when it
- * is needed. Note that not all cases require the string to be
- * reallocated.
- */
 extern int
  Base64Pad(char **, size_t);