From 4743498ad99916a2f3c61d84914cd9aa9a3be6c1 Mon Sep 17 00:00:00 2001 From: "psyc://loupsycedyglgamf.onion/~lynX" Date: Wed, 4 Apr 1984 00:44:05 +0000 Subject: [PATCH] augmented documentation --- include/psyc/match.h | 19 ++++++++++++++++--- include/psyc/method.h | 17 +++++++++++++---- include/psyc/packet.h | 4 ++++ include/psyc/parse.h | 3 ++- include/psyc/uniform.h | 5 +++++ include/psyc/variable.h | 2 +- 6 files changed, 41 insertions(+), 9 deletions(-) diff --git a/include/psyc/match.h b/include/psyc/match.h index f94aad2..9943499 100644 --- a/include/psyc/match.h +++ b/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); diff --git a/include/psyc/method.h b/include/psyc/method.h index 8375c19..dbb0226 100644 --- a/include/psyc/method.h +++ b/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_ACTION, + PSYC_MC_MESSAGE, // deprecated, use _converse + 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_action; + PsycString _message; // deprecated, use _converse + PsycString _message_action; // deprecated, use _converse PsycString _notice; PsycString _notice_alias_add; PsycString _notice_alias_change; diff --git a/include/psyc/packet.h b/include/psyc/packet.h index a319196..327b4a0 100644 --- a/include/psyc/packet.h +++ b/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, diff --git a/include/psyc/parse.h b/include/psyc/parse.h index 0ae1ca8..8b67305 100644 --- a/include/psyc/parse.h +++ b/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, diff --git a/include/psyc/uniform.h b/include/psyc/uniform.h index 80488cf..8c5021d 100644 --- a/include/psyc/uniform.h +++ b/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 = '~', diff --git a/include/psyc/variable.h b/include/psyc/variable.h index 38981ba..ac9c05e 100644 --- a/include/psyc/variable.h +++ b/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.