Document TelodendriaConfig

TODO.txt

@@ -36,7 +36,7 @@ Due: January 1, 2023
 		[ ] Matrix
 		[x] Queue
 		[ ] Routes
-		[ ] TelodendriaConfig
+		[x] TelodendriaConfig
 		[x] Util
 		[x] Memory
 		[x] Db

man/man3/TelodendriaConfig.3

@@ -0,0 +1,95 @@
+.Dd $Mdocdate: December 10 2022 $
+.Dt TELODENDRIACONFIG 3
+.Os Telodendria Project
+.Sh NAME
+.Nm TelodendriaConfig
+.Nd Parse the configuration file into a structure.
+.Sh SYNOPSIS
+.In TelodendriaConfig.h
+.Ft TelodendriaConfig *
+.Fn TelodendriaConfigParse "HashMap *" "LogConfig *"
+.Ft void
+.Fn TelodendriaConfigFree "TelodendriaConfig *"
+.Sh DESCRIPTION
+.Pp
+Validate and maintain the Telodendria server's configuration data. This API
+builds on the JSON API to add Telodendria-specific parsing. It takes a
+fully-parsed JSON object and converts it into a TelodendriaConfig, which is
+much more structured and easier to work with than the JSON. The config
+structure is not opaque like many other structures in Telodendria. This is
+intentional; defining functions for all of the fields would just add a lot
+of unecessary overhead. The structure is defined as follows:
+.Bd -literal -offset indent
+typedef struct TelodendriaConfig
+{
+	char *serverName;
+	char *baseUrl;
+	char *identityServer;
+
+	char *uid;
+	char *gid;
+	char *dataDir;
+
+	unsigned short listenPort;
+	unsigned int flags;
+	unsigned int threads;
+	unsigned int maxConnections;
+
+	size_t maxCache;
+
+	char *logTimestamp;
+	int logLevel;
+} TelodendriaConfig;
+.Ed
+.Pp
+Since the configuration will live in memory for a long time, it is important
+that unused values are freed as soon as possible. Therefore, the Telodendria
+structure is not opaque; values are accessed directly, and they can be
+freed as the program wishes. Do note that if you're going to free a value, you
+should set it to NULL, because
+.Fn TelodendriaConfigFree
+will unconditionally call
+.Fn Free
+on all values.
+.Pp
+The flags variable in this structure is a bit field that contains the OR-ed values
+of any of the given flags:
+.Bd -literal -offset indent
+typedef enum TelodendriaConfigFlag
+{
+	TELODENDRIA_FEDERATION,
+	TELODENDRIA_REGISTRATION,
+
+	TELODENDRIA_LOG_COLOR,
+
+	TELODENDRIA_LOG_FILE,
+	TELODENDRIA_LOG_STDOUT,
+	TELODENDRIA_LOG_SYSLOG
+} TelodendriaConfigFlag;
+.Ed
+.Pp
+Do note that the actual values of these enums are omitted, but they can be
+OR-ed together and added to flags.
+.Pp
+.Fn TelodendriaConfigParse
+parses a JSON map, extracting the necessary values, validating them, and then
+adding them to a new TelodendriaConfig for future use by the program. All values
+are copied, so the JSON hash map can be safely freed if this function
+succeeds. It takes a working log configuration so that messages can be written
+to the log as the parsing progresses, to warn users about default values and
+report errors, for example.
+.Pp
+.Fn TelodendriaConfigFree
+frees all of the memory allocated for the given configuration. This function
+unconditionally calls
+.Fn Free
+on all items in the structure, so make sure that items that were already freed
+are NULL.
+.Sh RETURN VALUES
+.Pp
+.Fn TelodendriaConfigParse
+returns a TelodendriaConfig that is completely independent of the passed
+configuration hash map, or NULL if one or more required values is missing, or
+there was some other error while parsing the configuration.
+.Sh SEE ALSO
+.Xr Json 3

site/index.html

@@ -241,6 +241,12 @@ A feature-complete API for reading and writing JSON.
 An extension to the Json API that implements Matrix's canonical JSON.
 </td>
 </tr>
+<tr>
+<td><a href="man/man3/TelodendriaConfig.3.html">TelodendriaConfig(3)</a></td>
+<td>
+Parse the configuration file into a structure.
+</td>
+</tr>
 </table>
 <h2 id="resources">Resources</h2>
 <ul>

src/include/TelodendriaConfig.h

@@ -22,12 +22,6 @@
  * SOFTWARE.
  */
 
-/*
- * TelodendriaConfig.h: Validate and maintain the Telodendria server's
- * configuration data. This API builds on the Config API to add
- * Telodendria-specific parsing. It takes a fully parsed Config, and
- * converts it into a TelodendriaConfig, which is more structured.
- */
 #ifndef TELODENDRIA_TELODENDRIACONFIG_H
 #define TELODENDRIA_TELODENDRIACONFIG_H
 
@@ -44,15 +38,6 @@ typedef enum TelodendriaConfigFlag
     TELODENDRIA_LOG_SYSLOG = (1 << 5)
 } TelodendriaConfigFlag;
 
-/*
- * Since this configuration will live in memory for a long time, it is
- * important that unused values are freed as soon as possible. Therefore,
- * the TelodendriaConfig structure is not opaque; values are accessed
- * directly, and they can be freed as the program wishes.
- *
- * NOTE: If you're going to free a value, make sure you set the pointer
- * to NULL. TelodendriaConfigFree() will call free() on all values.
- */
 typedef struct TelodendriaConfig
 {
     char *serverName;
@@ -74,35 +59,9 @@ typedef struct TelodendriaConfig
     int logLevel;
 } TelodendriaConfig;
 
-/*
- * Parse a Config map, extracting the necessary values, validating them,
- * and then adding them to a new TelodendriaConfig for future use by the
- * program. All values are copied, so the Config hash map can be safely
- * freed if this function succeeds.
- *
- * Params:
- *   (HashMap *)   A hash map from ConfigParse(). This should be a map of
- *                 ConfigDirectives.
- *   (LogConfig *) A working log configuration. Messages are written to
- *                 this log as the parsing progresses, and this log is
- *                 copied into the resulting TelodendriaConfig. It is
- *                 also potentially modified by the configuration file's
- *                 "log" block.
- *
- * Return: A TelodendriaConfig that is completely independent of the passed
- * configuration hash map, or NULL if one or more required values is missing.
- */
 extern TelodendriaConfig *
  TelodendriaConfigParse(HashMap *, LogConfig *);
 
-/*
- * Free all of the memory allocated to the given configuration. This
- * function unconditionally calls free() on all items in the structure,
- * so make sure items that were already freed are NULL.
- *
- * Params:
- *   (TelodendriaConfig *) The configuration to free all the values for.
- */
 extern void
  TelodendriaConfigFree(TelodendriaConfig *);