[AYA] See alsos, live-alongs, more documentation

I need to work on _actual_ Parsee, now

src/include/AS.h

@@ -1,5 +1,11 @@
 #ifndef PARSEE_AS_H
 #define PARSEE_AS_H
+/*-* 
+ * Functions used to communicate with a Matrix server and execute actions 
+ * over HTTP(S)+JSON. This effectively serves as Parsee's Matrix SDK.
+ * TODO: Write my own RanSDK for KappaChat.
+ * --------
+ * Writren-By: LDA */
 
 #include <Cytoplasm/HttpClient.h>
 #include <Cytoplasm/Json.h>
@@ -7,9 +13,11 @@
 #include <Parsee.h>
 #include <Routes.h>
 
-/* Verifies a request from the homeserver to match the 
- * hs_token. */
-extern HashMap * ASVerifyRequest(ParseeHttpArg *);
+/** Verifies a request from the homeserver to match the {hs_token}.
+ * ----------------
+ * Returns: A JSON error message[HEAP] | NULL on success 
+ * Thrasher: JsonFree */
+extern HashMap * ASVerifyRequest(ParseeHttpArg *arg);
 
 /* Authenticates a request with the correct as_token.
  * It does not send the request, however. */
@@ -49,8 +57,19 @@ extern void ASRedact(const ParseeConfig *, char *room, char *user, char *e_id);
 /* Sets a state event with a specific type and body */
 extern void ASSetState(const ParseeConfig *conf, char *id, char *type, char *key, char *mask, HashMap *event);
 
-/* Gets/Sets the content for a PL event */
+/** Gets the content for a PL event in the room pointed by {id}
+ * ------------------------
+ * Returns: A valid JSON object[HEAP] | NULL 
+ * Thrasher: JsonFree 
+ * See-Also: ASSetPL */
 extern HashMap *ASGetPL(const ParseeConfig *conf, char *id);
+
+/** Sets the content for a PL event in the room pointed by {id} if 
+ * possible.
+ * ------------------------
+ * Returns: NOTHING
+ * Modifies: the room pointed by {id}
+ * See-Also: ASGetPL */
 extern void ASSetPL(const ParseeConfig *conf, char *id, HashMap *m);
 
 /* Creates a room, with a masquerade user as its creator. This function 
@@ -62,14 +81,14 @@ extern char * ASCreateDM(const ParseeConfig *c, char *by, char *with);
 /** Sets the user's global display{name}
  * --------
  * Returns: NOTHING
- * Modifies: [EXT:User status]
+ * Modifies: the users' status in Matrix
  * See-Also: ASGetName, ASSetStatus, ASSetAvatar */
 extern void ASSetName(const ParseeConfig *c, char *user, char *name);
 
 /** Sets the {user}'s global avatar, as an {mxc} URI
  * --------
  * Returns: NOTHING
- * Modifies: [EXT:User status]
+ * Modifies: the users' status in Matrix
  * See-Also: ASGetName, ASSetStatus */
 extern void ASSetAvatar(const ParseeConfig *c, char *user, char *mxc);
 
@@ -81,18 +100,32 @@ typedef enum UserStatus {
 /** Sets the user's status and message, to be seen by other clients.
  * --------
  * Returns: NOTHING
- * Modifies: [EXT:User status]
+ * Modifies: the users' status in Matrix
  * See-Also: https://spec.matrix.org/v1.11/client-server-api/#put_matrixclientv3presenceuseridstatus, ASSetName, ASSetAvatar */
 extern void ASSetStatus(const ParseeConfig *c, char *user, UserStatus status, char *msg);
 
-/* Returns the user's name in a room, or a copy of the MXID itself, to be 
- * Free'd. */
+/** Returns the user's name in a room, or a copy of the MXID itself, to be 
+ * Free'd
+ * ------------- 
+ * Returns: The user's name in the room[HEAP] | A copy of {user}[HEAP]
+ * Thrasher: Free
+ * Modifies: NOTHING */
 extern char * ASGetName(const ParseeConfig *c, char *room, char *user);
 
-/* Uploads data to Matrix to be used later */
+/** Uploads data to Matrix to be used later
+ * ----------------
+ * Returns: A valid MXC URI[HEAP] | NULL
+ * Thrasher: Free 
+ * Modifies: the internal Matrix homeserver's media repository
+ * See-Also: ASReupload */
 extern char * ASUpload(const ParseeConfig *c, Stream *from, unsigned int size, char *mime);
 
-/* Reuploads a HTTP URL to Matrix, with an optional MIME type returned. */
+/** Reuploads a HTTP URL to Matrix, with an optional MIME type returned.
+ * ----------------
+ * Returns: A valid MXC URI[HEAP] | NULL
+ * Thrasher: Free 
+ * Modifies: the internal Matrix homeserver's media repository, {from}s server
+ * See-Also: ASUpload */
 extern char * ASReupload(const ParseeConfig *c, char *from, char **mime);
 
 extern HashMap * ASGetUserConfig(const ParseeConfig *c, char *user, char *key);

src/include/Command.h

@@ -1,5 +1,9 @@
 #ifndef PARSEE_COMMAND_H
 #define PARSEE_COMMAND_H
+/*-*
+ * A Matrix command manager (with a JCL/dd-style format).
+ * -----------
+ * Written-By: LDA */
 
 #include <Cytoplasm/HashMap.h>
 

src/include/Glob.h

@@ -1,10 +1,17 @@
 #ifndef PARSEE_GLOB_H
 #define PARSEE_GLOB_H
+/*-*
+ * A simple Matrix globrule matcher.
+ * -----------------
+ * Written-By: LDA */
 
 #include <stdbool.h>
 
-/* Verifies if a string matches a rule, as specified in 
- * https://spec.matrix.org/v1.11/appendices/#glob-style-matching. */
+/** Verifies if a string matches a rule, as specified in the Matrix 
+ * specification on globrules.
+ * -----------------
+ * Returns: true if it does match, otherwise false
+ * See-Also https://spec.matrix.org/v1.11/appendices/#glob-style-matching */
 extern bool GlobMatches(char *rule, char *string);
 
 #endif

src/include/Parsee.h

@@ -1,6 +1,11 @@
 #ifndef PARSEE_PARSEE_H
 #define PARSEE_PARSEE_H
 
+/*-* <p>Some fields used as Parsee-specific functions/structures.</p>
+ *   <p>TODO: Consider separating some declarations here...</p>
+ * --------
+ * Writren-By: LDA */
+
 #include <Cytoplasm/HttpServer.h>
 #include <Cytoplasm/HttpRouter.h>
 #include <Cytoplasm/HttpClient.h>
@@ -107,7 +112,11 @@ extern char * ParseeEncodeMXID(char *);
 extern char * ParseeDecodeMXID(char *);
 
 
-/* HTTP server handler for Parsee, takes in a config. */
+/** Callback function for the Parsee HTTP handler, to be used by 
+ * the HTTP thread itself.
+ * --------
+ * UB-If: not used as the HTTP callback function
+ * Returns: NOTHING */
 extern void ParseeRequest(HttpServerContext *, void *);
 
 /* A pthread callback used for listening to a component */
@@ -219,38 +228,61 @@ extern void ParseePushHeadTable(char *room, char *id);
 extern char *ParseeLookupHead(char *room);
 extern void ParseeDestroyHeadTable(void);
 
-/* Globally bans a Matrix user from ever interacting with Parsee, and bans 
- * them from bridged rooms where the bot has administrator. */
+/* Disables a user/room/MUC's ability to interact from Parsee, and attempts 
+ * to ban them from rooms where Parsee has the ability to do so ("noflying").
+ * ---------------
+ * Returns: NOTHING
+ * See-Also: ParseeManageBan
+ * Modifies: the database */
 extern void ParseeGlobalBan(ParseeData *, char *user, char *reason);
 
-/* Verifies if a user was globally banned. If so, then apply actions to the 
- * room ID */
+/* Verifies if a user was banned globally. If so (and if {room} is set), 
+ * tries to ban the user from it.
+ * ---------------
+ * Returns: NOTHING
+ * See-Also: ParseeManageBan
+ * Modifies: the database */
 extern bool ParseeManageBan(ParseeData *, char *user, char *room);
 
 /* Same as ParseeVerifyStanza, but DMs */
 extern bool ParseeVerifyDMStanza(ParseeData *data, char *room_id, char *id);
 
 
-/* Checks if any user is an admin */
+/** Checks if a Matrix/XMPP user is considered as "administrator" by Parsee.
+ * ----------------------
+ * Returns: (whenever the user is an admin)
+ * Modifies: NOTHING */
 extern bool ParseeIsAdmin(ParseeData *data, char *user);
 
-/* Measures Parsee's overall uptime */
+/* Measures Parsee's overall uptime.
+ * ----------------
+ * Returns: uptime since the call to Main in milliseconds. 
+ * Modifies: NOTHING */
 extern uint64_t ParseeUptime(void);
 
-/** Turns a duration into a nice "X minutes, Y seconds" string
+/** Turns a duration into a nice <code>"X minutes, Y seconds"</code>
+ * string.
  * ---------
  * Returns: A human-readable string showing the duration[LA:HEAP]
  * Modifies: NOTHING */
 extern char * ParseeStringifyDate(uint64_t millis);
 
-/* Generates the JID of the Parsee bridge user. */
+/** Generates the Jabber ID of the main Parsee user available.
+ * ----------------------
+ * Returns: An XMPP JID[LA:HEAP]
+ * Thrasher: Free */
 extern char * ParseeJID(ParseeData *data);
+
+/** Generates the MXID of the main Parsee user available.
+ * ----------------------
+ * Returns: A Matrix ID[LA:HEAP]
+ * Thrasher: Free */
 extern char * ParseeMXID(ParseeData *data);
 
 /** Prints an _fatal_ and _strange_, error message, then congratulates 
- * the user for it(an "achievement").
- * Use this for errors that have _no business_ happening, at all. 
- * NOTE to users: If you see this, _*OPEN AN ISSUE*_. 
+ * the user for it(an "achievement").<br/>
+ * Use this for errors that have <i>no business</i> happening, at all. 
+ * NOTE to users: If you see this, <u><i>OPEN AN ISSUE</i></u>.
  * ---------------------------------------------------
  * Returns: NOTHING | NORETURN */
 extern void ParseeAchievement(const char *func, const char *msg, bool die);

src/include/Routes.h

@@ -1,6 +1,11 @@
 #ifndef PARSEE_ROUTES_H
 #define PARSEE_ROUTES_H
 
+/*-*
+ * The HTTP routes and Matrix bot endpoints for Parser
+ * -----------
+ * Written-By: LDA */
+
 #include <Parsee.h>
 typedef struct ParseeHttpArg {
     ParseeData *data;

src/include/XEP393.h

@@ -1,6 +1,11 @@
 #ifndef PARSEE_XEP393_H
 #define PARSEE_XEP393_H
 
+/*-* 
+ * A basic XEP-0393 parser and XHTML-iser.
+ * --------
+ * Writren-By: LDA */
+
 #include <Cytoplasm/Array.h>
 
 typedef enum XEP393Type {

src/include/XMPP.h

@@ -1,6 +1,11 @@
 #ifndef PARSEE_XMPP_H
 #define PARSEE_XMPP_H
 
+/*-* 
+ * Functions used to communicate with an XMPP server over an JCP stream.
+ * --------
+ * Writren-By: LDA */
+
 #include <Cytoplasm/Stream.h>
 
 #include <pthread.h>