From d50b1c8b31570d0aa3dbdd6f917880b99deb3cc3 Mon Sep 17 00:00:00 2001 From: Krista 'DarthMama' Bennett Date: Mon, 2 Nov 2020 16:11:27 +0100 Subject: [PATCH] attempts to generate sync doc --- engine_doxygen.conf | 6 +- sync/gen_message_func.ysl2 | 127 +++++++++++++++++++++++++++---------- sync/gen_statemachine.ysl2 | 110 ++++++++++++++++++++++++++++---- 3 files changed, 197 insertions(+), 46 deletions(-) diff --git a/engine_doxygen.conf b/engine_doxygen.conf index bf40a938..84e74554 100644 --- a/engine_doxygen.conf +++ b/engine_doxygen.conf @@ -38,7 +38,7 @@ PROJECT_NAME = Engine # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = "2.1.0 RC28" +PROJECT_NUMBER = "2.2.0" # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a @@ -814,7 +814,7 @@ WARN_FORMAT = "$file:$line: $text" # messages should be written. If left blank the output is written to standard # error (stderr). -WARN_LOGFILE = "/Users/krista/src/pEpEngine/doxy_warnings.txt" +WARN_LOGFILE = "" #--------------------------------------------------------------------------- # Configuration options related to the input files @@ -826,7 +826,7 @@ WARN_LOGFILE = "/Users/krista/src/pEpEngine/doxy_warnings.txt" # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = /Users/krista/src/pEpEngine/src +INPUT = ./src ./asn.1 # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses diff --git a/sync/gen_message_func.ysl2 b/sync/gen_message_func.ysl2 index 253df525..8b787758 100644 --- a/sync/gen_message_func.ysl2 +++ b/sync/gen_message_func.ysl2 @@ -24,7 +24,7 @@ template "protocol", mode=header || /** * @file «@name»_func.h - * @brief States and functions for the «@name» protocol. + * @brief State storage and retrieval, and associated «@name» message generation and processing, for the «@name» protocol. * @generated from ../sync/gen_message_func.ysl2 * * @license GNU General Public License 3.0 - see LICENSE.txt @@ -41,39 +41,48 @@ extern "C" { #include "../asn.1/«@name».h" `` for "func:distinctType(fsm/message/field[not(func:basicType())])" | #include "../asn.1/«@type».h" -// state - +/** + * State information and associated stored data for all «@name» state machines + */ struct «@name»_state_s { - // own state + /** + * @struct «@name»_state_s::own_«@name»_state_s + * @brief Own state storage. + */ struct own_«@name»_state_s { - stringlist_t *keys; - stringlist_t *backup; - identity_list *identities; - `` for "fsm/message[@ratelimit>0]" |>> time_t last_«../@name»_«@name»; + stringlist_t *keys; //!< own keys + stringlist_t *backup; //!< ???? + identity_list *identities; //!< own identities + `` for "fsm/message[@ratelimit>0]" |>> time_t last_«../@name»_«@name»; //!< Timestamp of last «../@name» «@name» message accepted // TIDs we're using ourselves - `` for "func:distinctName(fsm/message/field[@type='TID'])" |>> «func:ctype()» «@name»; - } own; - - // state we learned about our communication partner + `` for "func:distinctName(fsm/message/field[@type='TID'])" |>> «func:ctype()» «@name»; //!< own «@name» TID + } own; /*!< Own state storage */ + /** + * @struct «@name»_state_s::comm_partner_state_s + * @brief State acquired from our communications partner + */ struct comm_partner_state_s { // transport data we expect - char *sender_fpr; - pEp_identity *identity; + char *sender_fpr; //!< sender fpr for comm partner that we expect all sender messages to be signed by + pEp_identity *identity; //!< comm partner identity // TIDs our comm partner wants to have - `` for "func:distinctName(fsm/message/field[@type='TID'])" |>> «func:ctype()» «@name»; - } comm_partner; - - // input buffer for actual transport data coming in + `` for "func:distinctName(fsm/message/field[@type='TID'])" |>> «func:ctype()» «@name»; //!< sender's «@name» TID + } comm_partner; /*!< Received comm partner state storage */ + /** + * @struct «@name»_state_s::transport_data_s + * @brief Input buffer for actual transport data coming in + */ struct transport_data_s { // transport data we got - pEp_identity *from; - char *sender_fpr; - } transport; + pEp_identity *from; //!< identity of the sender of incoming transport data + char *sender_fpr; //!< sender fpr for sender of incoming transport data + } transport; /*!< transport input buffer */ + `` apply "fsm", mode=state }; @@ -92,29 +101,72 @@ void free_«@name»_state(PEP_SESSION session); /** * * - * @brief create a new «@name» message of the indicated type + * @brief Generate new «@name»_t message structure of the given message type + * for the input finite state machine type * - * @param[in] fsm the state machine - * @param[in] message_type the type of «@name» message to be created + * @param[in] fsm current state machine type (??) + * @param[in] message_type the type of «@name» message struct to be created (with empty data) * - * @return ??? + * @return message the message struct desired + * @return NULL if the message_type is unknown * + * @TODO This description comes entirely from code inspection, but is probably + * better optimised by the author. Caveat lector - I may have gotten it wrong. */ «@name»_t *new_«@name»_message(«@name»_PR fsm, int message_type); /** * * - * @brief free a «@name» message struct + * @brief free a/an «@name»_t asn.1 message struct * - * @param[in] msg the desired message + * @param[in] msg the «@name»_t message struct to free * + * @TODO This description comes entirely from code inspection, but is probably + * better optimised by the author. Caveat lector - I may have gotten it wrong. */ void free_«@name»_message(«@name»_t *msg); +/** + * + * + * @brief Given a/an «@name» message and its corresponding finite state machine, + * update the session's state for its «@name» state machine given the information + * decoded from the message. + * + * This function takes a «@name» message and, depending on the type of «@name» message it is, + * (determined during parsing), copies the relevant data from the message struct into the + * corresponding session state structures as a utf8 string. + * + * @param[in] session session associated with the «@name» finite state machine + * @param[in] msg the message struct containing «@name» data (asn.1 - XER?) + * @param[out] fsm present finite state machine type indicated by the message + * @param[out] message_type the type of the message that was sent in + * + * @retval status + * + * @TODO This description comes entirely from code inspection, but is probably + * better optimised by the author. Caveat lector - I may have gotten it wrong. + * + */ PEP_STATUS update_«@name»_state(PEP_SESSION session, «@name»_t *msg, «@name»_PR *fsm, int *message_type); +/** + * + * + * @brief Given a «@name»_t message struct, fill in the relevant data for that message type and + * the state machine type indicated in the message from the current information contained + * in the session according to the message type indicated on the message struct + * + * @param[in] session the session from which to take the «@name» data + * @param[in] msg the «@name»_t message structure + * + * @retval status + * + * @TODO This description comes entirely from code inspection, but is probably + * better optimised by the author. Caveat lector - I may have gotten it wrong. + */ PEP_STATUS update_«@name»_message(PEP_SESSION session, «@name»_t *msg); #ifdef __cplusplus @@ -126,20 +178,31 @@ PEP_STATUS update_«@name»_message(PEP_SESSION session, «@name»_t *msg); template "fsm", mode=state || -// input/output buffer for «@name» messages +/** +* @struct «../@name»::_«@name»_state_s +* @brief Input/output buffer for «@name» messages +* +* @note Can't find a good way to generate documentation for the fields here. +*/ struct _«@name»_state_s { - int state; + int state; //!< current «@name» state `` for "func:distinctName(message/field)" |> «func:ctype()» «@name»; -} «yml:lcase(@name)»; +} «yml:lcase(@name)»; /*!< «@name» message Input/output buffer */ || template "protocol", mode=impl document "generated/{@name}_func.c", "text" { || -// This file is under GNU General Public License 3.0 -// see LICENSE.txt +/** + * @file «@name»_func.c + * @brief Implementation of tate storage and retrieval, and associated «@name» message + * generation and processing, for the «@name» protocol. + * @generated from ../sync/gen_message_func.ysl2 + * + * @license GNU General Public License 3.0 - see LICENSE.txt + */ #include #include diff --git a/sync/gen_statemachine.ysl2 b/sync/gen_statemachine.ysl2 index d142ed74..a0bd3380 100644 --- a/sync/gen_statemachine.ysl2 +++ b/sync/gen_statemachine.ysl2 @@ -32,20 +32,29 @@ tstylesheet { extern "C" { #endif + /** + * «@name» is also defined as «yml:ucase(@name)» for ASN.1 reasons and + * forward declaration to avoid the need for header inclusion everywhere. + * @see struct «@name» in «@name».h + */ typedef struct «@name» «yml:ucase(@name)»; + /** forward declaration - @see enum «@name»_PR in «@name».h */ typedef int «yml:ucase(@name)»_PR; + /** + * Data for an event related to a message + */ typedef struct «@name»_event { // state machine data - «yml:ucase(@name)»_PR fsm; - int event; - «yml:ucase(@name)» *msg; + «yml:ucase(@name)»_PR fsm; /*!< state machine type associated with this event */ + int event; /*!< type of event */ + «yml:ucase(@name)» *msg; /*!< the «@name» messaged caused by (or causing???) this event */ // transport data - pEp_identity *from; - char *sender_fpr; + pEp_identity *from; /*!< identity of the message sender */ + char *sender_fpr; /*!< fpr of key used by the message sender */ - identity_list *own_identities; + identity_list *own_identities; /*!< List of our own identities */ } «@name»_event_t; /** @@ -270,7 +279,7 @@ tstylesheet { ); ///////////////////////////////////////////////////////////////////////////// - // API used by the engine internally // + // API used by the engine internally // ///////////////////////////////////////////////////////////////////////////// /** @@ -1190,6 +1199,20 @@ tstylesheet { template "fsm", mode=timeout || + /** + * + * + * @internal + * + * @brief Determine if «@name» state machine has timed out + * (by hanging in the same state too long, + * exceeding «yml:ucase(@name)»_THRESHOLD) + * + * @param[in] state current state + * + * @retval true if wait has exceeded «yml:ucase(@name)»_THRESHOLD + * false otherwise + */ static bool _«@name»_timeout(int state) { static int last_state = None; @@ -1361,7 +1384,9 @@ tstylesheet { extern "C" { #endif + /////////////////////////////////////////////////////////////////////////////////////////// // state machine for «@name» + /////////////////////////////////////////////////////////////////////////////////////////// // states @@ -1397,16 +1422,49 @@ tstylesheet { || } «@name»_event; + // state machine #ifndef NDEBUG + /** + * + * + * @brief Convert «@name» state to string + * + * @param[in] state state to convert to string + * + * @retval string representation of state name + * NULL if invalid state + */ const char *«@name»_state_name(int state); + /** + * + * + * @brief Convert «@name» event to string + * + * @param[in] event event to convert to string + * + * @retval string representation of event name + * NULL if invalid event + */ const char *«@name»_event_name(int event); #endif - // the state machine function is returning the next state in case of a - // transition or None for staying - + /** + * + * + * @brief Given the current state of a «@name» state machine, determine if + * a received «@name» event will cause a state transition + * and, if so, return the next state. + * + * @param[in] session session state machine is associated with + * @param[in] state current state + * @param[in] event incoming event to evaluate + * + * @retval next_state if event causes a state transition + * @retval None if state machine should remain in the same state + * + */ «@name»_state fsm_«@name»( PEP_SESSION session, «@name»_state state, @@ -1479,7 +1537,20 @@ tstylesheet { } } - + /** + * + * + * @internal + * + * @brief Convert an integer to a string representation + * + * @param[in] n integer to convert + * @param[in] hex true if it should be in hex representation, + * false for decimal + * + * @retval string representation of input + * NULL if out of memory or input invalid + */ static char *_str(int n, bool hex) { char *buf = calloc(1, 24); @@ -1496,6 +1567,23 @@ tstylesheet { #define «@name»_ERR_LOG(t, d) log_event(session, (t), "«@name»", (d), "error") + /** + * + * + * @internal + * + * @brief Write a «@name» error to log with integer input as description + * + * @param[in] session relevant session + * @param[in] t C string event name + * @param[in] n integer to log (e.g. error status) + * @param[in] hex true if integer should be logged in hex format, + * false if decimal + * + * @retval PEP_OUT_OF_MEMORY if out of memory + * @retval PEP_ILLEGAL_VALUE if input error during logging + * @retval PEP_STATUS_OK otherwise + */ static PEP_STATUS _«@name»_ERR_LOG_int(PEP_SESSION session, char *t, int n, bool hex) { char *_buf = _str(n, hex);