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

I need to work on _actual_ Parsee, now

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);