buff
/
pEpEngine
forked from pEp.foundation/pEpEngine
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

attempts to generate sync doc

doxygen_doc
Krista 'DarthMama' Bennett 2020-11-02 16:11:27 +01:00
parent 4e772ae3e7
commit d50b1c8b31
3 changed files with 197 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
engine_doxygen.conf
View File

@ -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

127
sync/gen_message_func.ysl2
View File

@ -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);
/**
* <!-- new_«@name»_message() -->
*
* @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);
/**
* <!-- free_«@name»_message() -->
*
* @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);
/**
* <!-- update_«@name»_state() -->
*
* @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);
/**
* <!-- update_«@name»_message() -->
*
* @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 <assert.h>
#include <stdlib.h>

110
sync/gen_statemachine.ysl2
View File

@ -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
||
/**
* <!-- _«@name»_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
/**
* <!-- «@name»_state_name() -->
*
* @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);
/**
* <!-- «@name»_event_name() -->
*
* @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
/**
* <!-- fsm_«@name» -->
*
* @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 {
}
}
/**
* <!-- _str() -->
*
* @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")
/**
* <!-- _«@name»_ERR_LOG_int() -->
*
* @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);