augmented documentation

include/psyc/match.h

@@ -32,13 +32,27 @@ typedef struct {
 } PsycMapInt;
 
 /**
- * Checks if long keyword string inherits from short keyword string.
+ * Checks if long keyword string inherits from short keyword string
+ * according to the principles of PSYC keyword inheritance.
+ * See about:inheritance.
+ *
+ * @param sho Shorter string
+ * @param slen Shorter string length
+ * @param lon Longer string
+ * @param llen Longer string length
  */
 int
 psyc_inherits (char *sho, size_t slen, char *lon, size_t llen);
 
 /**
- * Checks if short keyword string matches long keyword string.
+ * Checks if short keyword string matches long keyword string
+ * according to the principles of PSYC keyword matching.
+ * See about:psycmatch.
+ *
+ * @param sho Shorter string
+ * @param slen Shorter string length
+ * @param lon Longer string
+ * @param llen Longer string length
  */
 int
 psyc_matches (char *sho, size_t slen, char *lon, size_t llen);
@@ -55,7 +69,6 @@ psyc_matches (char *sho, size_t slen, char *lon, size_t llen);
  *
  * @return The value of the entry if found, or NULL if not found.
  */
-
 void *
 psyc_map_lookup (const PsycMap *map, size_t size,
 		 const char *key, size_t keylen, PsycBool inherit);

include/psyc/method.h

@@ -21,6 +21,7 @@
 #ifndef PSYC_METHOD_H
 #define PSYC_METHOD_H
 
+/** Characteristics attributed to certain method families. */
 typedef enum {
     PSYC_METHOD_TEMPLATE = 1 << 0,
     PSYC_METHOD_REPLY    = 1 << 1,
@@ -29,9 +30,15 @@ typedef enum {
     PSYC_METHOD_MANUAL   = 1 << 4,
 } PsycMethodFlag;
 
+/**
+ * This is a preliminary set of methods, you will encounter a lot more in
+ * the wild. The definitive standardization and definition of compact methods
+ * will follow. "mc" is an old abbreviation for method.
+ */
 typedef enum {
     PSYC_MC_UNKNOWN,
 
+    PSYC_MC_CONVERSE,
     PSYC_MC_DATA,
     PSYC_MC_ECHO,
     PSYC_MC_ECHO_CONTEXT_ENTER,
@@ -42,8 +49,8 @@ typedef enum {
     PSYC_MC_FAILURE_ALIAS_NONEXISTANT,
     PSYC_MC_FAILURE_ALIAS_UNAVAILABLE,
     PSYC_MC_INFO,
-    PSYC_MC_MESSAGE,
+    PSYC_MC_MESSAGE,		// deprecated, use _converse
-    PSYC_MC_MESSAGE_ACTION,
+    PSYC_MC_MESSAGE_ACTION,	// deprecated, use _converse
     PSYC_MC_NOTICE,
     PSYC_MC_NOTICE_ALIAS_ADD,
     PSYC_MC_NOTICE_ALIAS_CHANGE,
@@ -68,10 +75,12 @@ typedef enum {
     PSYC_METHODS_NUM,
 } PsycMethod;
 
+/* Same list of typical but non-final methods again */
 typedef union PsycTemplates {
     PsycString a[PSYC_METHODS_NUM];
     struct {
 	PsycString _;
+	PsycString _converse;
 	PsycString _data;
 	PsycString _echo;
 	PsycString _echo_context_enter;
@@ -82,8 +91,8 @@ typedef union PsycTemplates {
 	PsycString _failure_alias_nonexistant;
 	PsycString _failure_alias_unavailable;
 	PsycString _info;
-	PsycString _message;
+	PsycString _message;		// deprecated, use _converse
-	PsycString _message_action;
+	PsycString _message_action;	// deprecated, use _converse
 	PsycString _notice;
 	PsycString _notice_alias_add;
 	PsycString _notice_alias_change;

include/psyc/packet.h

@@ -76,6 +76,7 @@
 # define PSYC_ELEM_SIZE_THRESHOLD 9
 #endif
 
+/** PSYC2 packet delimiter character */
 #define PSYC_PACKET_DELIMITER_CHAR '|'
 #define PSYC_PACKET_DELIMITER	   "\n|\n"
 
@@ -117,6 +118,7 @@ typedef enum {
     PSYC_PACKET_NO_LENGTH = 2,
 } PsycPacketFlag;
 
+/** Operators for modifying or querying PSYC state */
 typedef enum {
     PSYC_OPERATOR_SET = ':',
     PSYC_OPERATOR_ASSIGN = '=',
@@ -126,12 +128,14 @@ typedef enum {
     PSYC_OPERATOR_QUERY = '?',
 } PsycOperator;
 
+/* Reduced set of operators allowed in routing layer */
 typedef enum {
     PSYC_STATE_NOOP = 0,
     PSYC_STATE_RESET = '=',
     PSYC_STATE_RESYNC = '?',
 } PsycStateOp;
 
+/** Enumeration of standard routing variables */
 typedef enum {
     PSYC_PACKET_ID_CONTEXT = 0,
     PSYC_PACKET_ID_SOURCE = 1,

include/psyc/parse.h

@@ -137,6 +137,7 @@
 
 #include "../psyc.h"
 
+/** Options for selective parsing. */
 typedef enum {
     /// Default Flag. Parse everything.
     PSYC_PARSE_ALL = 0,
@@ -221,7 +222,7 @@ typedef enum {
     PSYC_PARSE_COMPLETE = 13,
 } PsycParseRC;
 
-/// PSYC packet parts.
+/** PSYC packet parts. */
 typedef enum {
     PSYC_PART_RESET = -1,
     PSYC_PART_ROUTING = 0,

include/psyc/uniform.h

@@ -85,6 +85,10 @@ typedef enum {
     PSYC_PARSE_UNIFORM_INVALID_SCHEME = -1,
 } PsycParseUniformRC;
 
+/**
+ * Accepted transport flags in PSYC uniforms.
+ * Appears after the hostname, the colon and the optional port number
+ */
 typedef enum {
     PSYC_TRANSPORT_TCP = 'c',
     PSYC_TRANSPORT_UDP = 'd',
@@ -92,6 +96,7 @@ typedef enum {
     PSYC_TRANSPORT_GNUNET = 'g',
 } PsycTransport;
 
+/** Characters indicating typical kinds of PSYC entities. */
 typedef enum {
     PSYC_ENTITY_ROOT = 0,
     PSYC_ENTITY_PERSON = '~',

include/psyc/variable.h

@@ -31,7 +31,7 @@
 /// Routing variables in alphabetical order.
 extern const PsycMapInt psyc_rvars[];
 
-// Variable types in alphabetical order.
+/// Variable types in alphabetical order.
 extern const PsycMapInt psyc_var_types[];
 
 /// Method names in alphabetical order.