internal function comment stubs

src/base64.c

@@ -28,6 +28,16 @@ static char translate_char_to_bits(char input) {
     return -1;    
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       _is_whitespace()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	in		constchar
+ *  
+ */
 static bool _is_whitespace(const char in) {
     switch (in) {
         case ' ':
@@ -40,6 +50,17 @@ static bool _is_whitespace(const char in) {
     }        
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       subtract_whitespace()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*input		constchar
+ *  @param[in]	length		int
+ *  
+ */
 static size_t subtract_whitespace(const char* input, int length) {
     size_t actual_size = length;
     int i;
@@ -51,6 +72,17 @@ static size_t subtract_whitespace(const char* input, int length) {
     return actual_size;
 }
     
+/**
+ *  @internal
+ *  
+ *  <!--       trim_end()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*input		constchar
+ *  @param[in]	*length		int
+ *  
+ */
 static void trim_end(const char* input, int* length) {
     const char* end = input + *length;
     
@@ -65,6 +97,17 @@ static void trim_end(const char* input, int* length) {
     }
 }    
     
+/**
+ *  @internal
+ *  
+ *  <!--       next_char()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	**input_ptr		constchar
+ *  @param[in]	*end		constchar
+ *  
+ */
 char next_char(const char** input_ptr, const char* end) {
     const char* input = *input_ptr;
     char this_ch = 0;

src/etpan_mime.c

@@ -22,6 +22,15 @@
 
 #define MAX_MESSAGE_ID 128
 
+/**
+ *  @internal
+ *  
+ *  <!--       generate_boundary()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  
+ */
 static char * generate_boundary(void)
 {
     char id[MAX_MESSAGE_ID];
@@ -804,6 +813,18 @@ char * _get_filename_or_cid(struct mailmime *mime)
     return _temp_filename_ptr;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       parameter_has_value()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*content		structmailmime_content
+ *  @param[in]	*name		constchar
+ *  @param[in]	*value		constchar
+ *  
+ */
 static bool parameter_has_value(
         struct mailmime_content *content,       
         const char *name,
@@ -880,6 +901,17 @@ bool _is_text_part(struct mailmime_content *content, const char *subtype)
     return false;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       _is_message_part()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*content		structmailmime_content
+ *  @param[in]	*subtype		constchar
+ *  
+ */
 bool _is_message_part(struct mailmime_content *content, const char* subtype) {
     assert(content);
     if (content->ct_type && content->ct_type->tp_type == MAILMIME_TYPE_COMPOSITE_TYPE &&
@@ -1038,6 +1070,17 @@ static PEP_STATUS interpret_MIME(struct mailmime *mime,
 // temporary files when the pgp/mime support was implemented for
 // outlook, as the existing code did not work well on windows.
 
+/**
+ *  @internal
+ *  
+ *  <!--       render_mime()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*mime		structmailmime
+ *  @param[in]	**mimetext		char
+ *  
+ */
 static PEP_STATUS render_mime(struct mailmime *mime, char **mimetext)
 {
     PEP_STATUS status = PEP_STATUS_OK;
@@ -1087,6 +1130,18 @@ pEp_error:
     return status;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       mime_attachment()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*blob		bloblist_t
+ *  @param[in]	**result		structmailmime
+ *  @param[in]	is_nf_message_attachment		bool
+ *  
+ */
 static PEP_STATUS mime_attachment(
         bloblist_t *blob,
         struct mailmime **result,
@@ -1144,6 +1199,19 @@ enomem:
 // "contained message" of pEp 2.x messages 
 // on the initial encoding where it is turned 
 // into attachment data!!
+/**
+ *  @internal
+ *  
+ *  <!--       mime_html_text()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*plaintext		constchar
+ *  @param[in]	*htmltext		constchar
+ *  @param[in]	*attachments		bloblist_t
+ *  @param[in]	**result		structmailmime
+ *  
+ */
 static PEP_STATUS mime_html_text(
         const char *plaintext,
         const char *htmltext,
@@ -1324,6 +1392,16 @@ enomem:
 }
 
 
+/**
+ *  @internal
+ *  
+ *  <!--       identity_to_mailbox()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*ident		constpEp_identity
+ *  
+ */
 static struct mailimf_mailbox * identity_to_mailbox(const pEp_identity *ident)
 {
     char *_username = NULL;
@@ -1354,6 +1432,16 @@ enomem:
     return NULL;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       identity_to_mbl()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*ident		constpEp_identity
+ *  
+ */
 static struct mailimf_mailbox_list * identity_to_mbl(
         const pEp_identity *ident)
 {
@@ -1392,6 +1480,16 @@ enomem:
     return NULL;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       identity_list_to_mal()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*il		identity_list
+ *  
+ */
 static struct mailimf_address_list * identity_list_to_mal(identity_list *il)
 {
     struct mailimf_address_list *mal = NULL;
@@ -1444,6 +1542,17 @@ enomem:
 // KB: This seems to be always called with "true",
 //     but there was probably a reason for this. So 
 //     leave it for now.
+/**
+ *  @internal
+ *  
+ *  <!--       stringlist_to_clist()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*sl		stringlist_t
+ *  @param[in]	transport_encode		bool
+ *  
+ */
 static clist * stringlist_to_clist(stringlist_t *sl, bool transport_encode)
 {
     clist * cl = clist_new();
@@ -1477,6 +1586,17 @@ static clist * stringlist_to_clist(stringlist_t *sl, bool transport_encode)
     return cl;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       build_fields()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*msg		constmessage
+ *  @param[in]	**result		structmailimf_fields
+ *  
+ */
 static PEP_STATUS build_fields(const message *msg, struct mailimf_fields **result)
 {
     PEP_STATUS status = PEP_STATUS_OK;
@@ -1706,6 +1826,16 @@ enomem:
     return status;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       has_exceptional_extension()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*filename		char
+ *  
+ */
 static bool has_exceptional_extension(char* filename) {
     if (!filename)
         return false;
@@ -1719,6 +1849,16 @@ static bool has_exceptional_extension(char* filename) {
     return false;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       choose_resource_id()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*rid_list		pEp_rid_list_t
+ *  
+ */
 static pEp_rid_list_t* choose_resource_id(pEp_rid_list_t* rid_list) {
     pEp_rid_list_t* retval = rid_list;
     
@@ -1768,6 +1908,19 @@ static pEp_rid_list_t* choose_resource_id(pEp_rid_list_t* rid_list) {
 // }
 
 
+/**
+ *  @internal
+ *  
+ *  <!--       mime_encode_message_plain()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*msg		constmessage
+ *  @param[in]	omit_fields		bool
+ *  @param[in]	**result		structmailmime
+ *  @param[in]	has_pEp_msg_attachment		bool
+ *  
+ */
 static PEP_STATUS mime_encode_message_plain(
         const message *msg,
         bool omit_fields,
@@ -1923,6 +2076,18 @@ pEp_error:
     return status;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       mime_encode_message_PGP_MIME()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*msg		constmessage
+ *  @param[in]	omit_fields		bool
+ *  @param[in]	**result		structmailmime
+ *  
+ */
 static PEP_STATUS mime_encode_message_PGP_MIME(
         const message * msg,
         bool omit_fields,
@@ -2094,6 +2259,16 @@ pEp_error:
     return status;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       mailbox_to_identity()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*mb		conststructmailimf_mailbox
+ *  
+ */
 static pEp_identity *mailbox_to_identity(const struct mailimf_mailbox * mb)
 {
     char *username = NULL;
@@ -2141,12 +2316,32 @@ enomem:
     return NULL;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       mbl_to_identity()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*mbl		conststructmailimf_mailbox_list
+ *  
+ */
 static pEp_identity * mbl_to_identity(const struct mailimf_mailbox_list * mbl)
 {
     struct mailimf_mailbox * mb = clist_content(clist_begin(mbl->mb_list));
     return mailbox_to_identity(mb);
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       mal_to_identity_list()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*mal		conststructmailimf_address_list
+ *  
+ */
 static identity_list * mal_to_identity_list(
         const struct mailimf_address_list *mal
     )
@@ -2205,6 +2400,16 @@ enomem:
     return NULL;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       clist_to_stringlist()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*list		constclist
+ *  
+ */
 static stringlist_t * clist_to_stringlist(const clist *list)
 {
     char *text = NULL;;
@@ -2239,6 +2444,17 @@ enomem:
     return NULL;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       read_fields()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*msg		message
+ *  @param[in]	*fieldlist		clist
+ *  
+ */
 static PEP_STATUS read_fields(message *msg, clist *fieldlist)
 {
     PEP_STATUS status = PEP_STATUS_OK;
@@ -2449,6 +2665,18 @@ pEp_error:
     return status;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       interpret_body()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*part		structmailmime
+ *  @param[in]	**longmsg		char
+ *  @param[in]	*size		size_t
+ *  
+ */
 static PEP_STATUS interpret_body(struct mailmime *part, char **longmsg, size_t *size)
 {
     const char *text;
@@ -2526,6 +2754,17 @@ static PEP_STATUS interpret_body(struct mailmime *part, char **longmsg, size_t *
 
 // THIS IS A BEST-EFFORT ONLY FUNCTION, AND WE ARE NOT DOING MORE THAN THE
 // SUBJECT FOR NOW.
+/**
+ *  @internal
+ *  
+ *  <!--       interpret_protected_headers()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*mime		structmailmime
+ *  @param[in]	*msg		message
+ *  
+ */
 static PEP_STATUS interpret_protected_headers(
         struct mailmime* mime, 
         message* msg
@@ -2566,6 +2805,17 @@ static PEP_STATUS interpret_protected_headers(
 }
 
 // ONLY for main part!!!
+/**
+ *  @internal
+ *  
+ *  <!--       process_multipart_related()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*mime		structmailmime
+ *  @param[in]	*msg		message
+ *  
+ */
 static PEP_STATUS process_multipart_related(struct mailmime *mime,
                                             message *msg) {
     PEP_STATUS status = PEP_STATUS_OK;
@@ -2622,6 +2872,16 @@ static PEP_STATUS process_multipart_related(struct mailmime *mime,
     return status;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       _is_marked_as_attachment()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*fields		structmailmime_fields
+ *  
+ */
 static bool _is_marked_as_attachment(struct mailmime_fields *fields)
 {
     if (!(fields && fields->fld_list))
@@ -2642,6 +2902,18 @@ static bool _is_marked_as_attachment(struct mailmime_fields *fields)
     return false;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       interpret_MIME()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*mime		structmailmime
+ *  @param[in]	*msg		message
+ *  @param[in]	*has_possible_pEp_msg		bool
+ *  
+ */
 static PEP_STATUS interpret_MIME(
         struct mailmime *mime,
         message *msg,

src/key_reset.c

@@ -23,11 +23,37 @@
 #define KEY_RESET_MAJOR_VERSION 1L
 #define KEY_RESET_MINOR_VERSION 0L
 
+/**
+ *  @internal
+ *  
+ *  <!--       _add_auto_consume()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*msg		message
+ *  
+ */
 static void _add_auto_consume(message* msg) {
     add_opt_field(msg, "pEp-auto-consume", "yes");
     msg->in_reply_to = stringlist_add(msg->in_reply_to, "pEp-auto-consume@pEp.foundation");
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       _generate_reset_structs()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  @param[in]	*reset_ident		constpEp_identity
+ *  @param[in]	*old_fpr		constchar
+ *  @param[in]	*new_fpr		constchar
+ *  @param[in]	**key_attachments		bloblist_t
+ *  @param[in]	**command_list		keyreset_command_list
+ *  @param[in]	include_secret		bool
+ *  
+ */
 static PEP_STATUS _generate_reset_structs(PEP_SESSION session,
                                           const pEp_identity* reset_ident,
                                           const char* old_fpr,
@@ -134,6 +160,19 @@ pEp_error:
 
 // For multiple idents under a single key
 // idents contain new fprs
+/**
+ *  @internal
+ *  
+ *  <!--       _generate_own_commandlist_msg()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  @param[in]	*from_idents		identity_list
+ *  @param[in]	*old_fpr		constchar
+ *  @param[in]	**dst		message
+ *  
+ */
 static PEP_STATUS _generate_own_commandlist_msg(PEP_SESSION session,
                                                 identity_list* from_idents,
                                                 const char* old_fpr,
@@ -218,6 +257,22 @@ pEp_error:
     return status;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       _generate_keyreset_command_message()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  @param[in]	*from_ident		constpEp_identity
+ *  @param[in]	*to_ident		constpEp_identity
+ *  @param[in]	*old_fpr		constchar
+ *  @param[in]	*new_fpr		constchar
+ *  @param[in]	is_private		bool
+ *  @param[in]	**dst		message
+ *  
+ */
 static PEP_STATUS _generate_keyreset_command_message(PEP_SESSION session,
                                                      const pEp_identity* from_ident,
                                                      const pEp_identity* to_ident,
@@ -942,6 +997,17 @@ DYNAMIC_API PEP_STATUS key_reset_all_own_keys(PEP_SESSION session) {
     return key_reset(session, NULL, NULL);
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       _dup_grouped_only()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*idents		identity_list
+ *  @param[in]	**filtered		identity_list
+ *  
+ */
 static PEP_STATUS _dup_grouped_only(identity_list* idents, identity_list** filtered) {
     if (!idents)
         return PEP_STATUS_OK;
@@ -975,6 +1041,17 @@ static PEP_STATUS _dup_grouped_only(identity_list* idents, identity_list** filte
     return PEP_STATUS_OK;    
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       _check_own_reset_passphrase_readiness()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  @param[in]	*key		constchar
+ *  
+ */
 static PEP_STATUS _check_own_reset_passphrase_readiness(PEP_SESSION session,
                                                         const char* key) { 
 
@@ -1036,6 +1113,19 @@ static PEP_STATUS _check_own_reset_passphrase_readiness(PEP_SESSION session,
 // FIXME:
 // I am not sure this is safe with already-revoked keys.
 //
+/**
+ *  @internal
+ *  
+ *  <!--       _key_reset_device_group_for_shared_key()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  @param[in]	*key_idents		identity_list
+ *  @param[in]	*old_key		constchar
+ *  @param[in]	grouped_only		bool
+ *  
+ */
 static PEP_STATUS _key_reset_device_group_for_shared_key(PEP_SESSION session, 
                                                          identity_list* key_idents, 
                                                          const char* old_key,
@@ -1566,6 +1656,17 @@ pEp_free:
     return status;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       Distribution_from_keyreset_command_list()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*command_list		constkeyreset_command_list
+ *  @param[in]	*dist		Distribution_t
+ *  
+ */
 Distribution_t *Distribution_from_keyreset_command_list(
         const keyreset_command_list *command_list,
         Distribution_t *dist
@@ -1671,6 +1772,17 @@ the_end:
     return status;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       Distribution_to_keyreset_command_list()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*dist		Distribution_t
+ *  @param[in]	*command_list		keyreset_command_list
+ *  
+ */
 keyreset_command_list * Distribution_to_keyreset_command_list(
         Distribution_t *dist,
         keyreset_command_list *command_list

src/keymanagement.c

@@ -44,6 +44,18 @@ static bool key_matches_address(PEP_SESSION session, const char* address,
 }
 
 // Does not return PASSPHRASE errors
+/**
+ *  @internal
+ *  
+ *  <!--       elect_pubkey()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  @param[in]	*identity		pEp_identity
+ *  @param[in]	check_blacklist		bool
+ *  
+ */
 PEP_STATUS elect_pubkey(
         PEP_SESSION session, pEp_identity * identity, bool check_blacklist
     )
@@ -113,6 +125,20 @@ PEP_STATUS elect_pubkey(
 // possibly having an own pubkey that we need to check on its own
 // N.B. Checked for PASSPHRASE errors - will now return them always
 // False value of "renew_private" prevents their possibility, though.
+/**
+ *  @internal
+ *  
+ *  <!--       validate_fpr()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  @param[in]	*ident		pEp_identity
+ *  @param[in]	check_blacklist		bool
+ *  @param[in]	own_must_contain_private		bool
+ *  @param[in]	renew_private		bool
+ *  
+ */
 static PEP_STATUS validate_fpr(PEP_SESSION session, 
                                pEp_identity* ident,
                                bool check_blacklist,
@@ -477,6 +503,17 @@ PEP_STATUS get_valid_pubkey(PEP_SESSION session,
     return status;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       transfer_ident_lang_and_flags()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*new_ident		pEp_identity
+ *  @param[in]	*stored_ident		pEp_identity
+ *  
+ */
 static void transfer_ident_lang_and_flags(pEp_identity* new_ident,
                                           pEp_identity* stored_ident) {
     if (new_ident->lang[0] == 0) {
@@ -489,6 +526,17 @@ static void transfer_ident_lang_and_flags(pEp_identity* new_ident,
     new_ident->me = new_ident->me || stored_ident->me;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       adjust_pEp_trust_status()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  @param[in]	*identity		pEp_identity
+ *  
+ */
 static void adjust_pEp_trust_status(PEP_SESSION session, pEp_identity* identity) {
     assert(session);
     assert(identity);
@@ -517,6 +565,19 @@ static void adjust_pEp_trust_status(PEP_SESSION session, pEp_identity* identity)
 // and friends NEVER return with a password error.
 // (get_valid_pubkey tells validate_fpr not to try renewal)
 // Will not return PASSPHRASE errors.
+/**
+ *  @internal
+ *  
+ *  <!--       prepare_updated_identity()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  @param[in]	*return_id		pEp_identity
+ *  @param[in]	*stored_ident		pEp_identity
+ *  @param[in]	store		bool
+ *  
+ */
 static PEP_STATUS prepare_updated_identity(PEP_SESSION session,
                                                  pEp_identity* return_id,
                                                  pEp_identity* stored_ident,
@@ -1028,6 +1089,17 @@ pEp_free:
     return status;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       elect_ownkey()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  @param[in]	*identity		pEp_identity
+ *  
+ */
 PEP_STATUS elect_ownkey(
         PEP_SESSION session, pEp_identity * identity
     )
@@ -1098,6 +1170,18 @@ PEP_STATUS elect_ownkey(
     return PEP_STATUS_OK;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       _has_usable_priv_key()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  @param[in]	*fpr		char
+ *  @param[in]	*is_usable		bool
+ *  
+ */
 PEP_STATUS _has_usable_priv_key(PEP_SESSION session, char* fpr,
                                 bool* is_usable) {
     
@@ -2119,6 +2203,17 @@ PEP_STATUS is_mistrusted_key(PEP_SESSION session, const char* fpr,
     return status;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       _wipe_default_key_if_invalid()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  @param[in]	*ident		pEp_identity
+ *  
+ */
 static PEP_STATUS _wipe_default_key_if_invalid(PEP_SESSION session,
                                          pEp_identity* ident) {
     

src/mime.c

@@ -12,6 +12,16 @@
 #include <assert.h>
 #include <errno.h>
 
+/**
+ *  @internal
+ *  
+ *  <!--       is_whitespace()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	c		char
+ *  
+ */
 static bool is_whitespace(char c)
 {
     switch (c) {

src/pEpEngine.c

@@ -539,6 +539,19 @@ static const char *sql_has_id_contacted_address =
 static const char *sql_get_last_contacted =
     "select user_id, address from identity where datetime('now') < datetime(timestamp, '+14 days') ; ";
         
+/**
+ *  @internal
+ *  
+ *  <!--       user_version()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*_version		void
+ *  @param[in]	count		int
+ *  @param[in]	**text		char
+ *  @param[in]	**name		char
+ *  
+ */
 static int user_version(void *_version, int count, char **text, char **name)
 {
     if (!(_version && count == 1 && text && text[0]))
@@ -550,6 +563,17 @@ static int user_version(void *_version, int count, char **text, char **name)
 }
 
 // TODO: refactor and generalise these two functions if possible.
+/**
+ *  @internal
+ *  
+ *  <!--       db_contains_table()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  @param[in]	*table_name		constchar
+ *  
+ */
 static int db_contains_table(PEP_SESSION session, const char* table_name) {
     if (!session || !table_name)
         return -1;
@@ -594,6 +618,18 @@ static int db_contains_table(PEP_SESSION session, const char* table_name) {
         
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       table_contains_column()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  @param[in]	*table_name		constchar
+ *  @param[in]	*col_name		constchar
+ *  
+ */
 static int table_contains_column(PEP_SESSION session, const char* table_name,
                                                       const char* col_name) {
 
@@ -644,6 +680,16 @@ static int table_contains_column(PEP_SESSION session, const char* table_name,
     return retval;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       repair_altered_tables()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  
+ */
 PEP_STATUS repair_altered_tables(PEP_SESSION session) {
     PEP_STATUS status = PEP_STATUS_OK;
     
@@ -822,6 +868,18 @@ pEp_free:
     free(table_names);
     return status;
 }
+/**
+ *  @internal
+ *  
+ *  <!--       errorLogCallback()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*pArg		void
+ *  @param[in]	iErrCode		int
+ *  @param[in]	*zMsg		constchar
+ *  
+ */
 void errorLogCallback(void *pArg, int iErrCode, const char *zMsg){
   fprintf(stderr, "(%d) %s\n", iErrCode, zMsg);
 }
@@ -3108,6 +3166,18 @@ PEP_STATUS get_identities_by_address(
     return PEP_STATUS_OK;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       exists_identity_entry()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  @param[in]	*identity		pEp_identity
+ *  @param[in]	*exists		bool
+ *  
+ */
 PEP_STATUS exists_identity_entry(PEP_SESSION session, pEp_identity* identity,
                                  bool* exists) {
     if (!session || !exists || !identity || EMPTYSTR(identity->user_id) || EMPTYSTR(identity->address))
@@ -3323,6 +3393,18 @@ PEP_STATUS set_or_update_with_identity(PEP_SESSION session,
     return status;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       _set_trust_internal()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  @param[in]	*identity		pEp_identity
+ *  @param[in]	guard_transaction		bool
+ *  
+ */
 PEP_STATUS _set_trust_internal(PEP_SESSION session, pEp_identity* identity,
                                bool guard_transaction) {
     return set_or_update_with_identity(session, identity,
@@ -3356,6 +3438,18 @@ PEP_STATUS set_person(PEP_SESSION session, pEp_identity* identity,
                                        guard_transaction);
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       set_identity_entry()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  @param[in]	*identity		pEp_identity
+ *  @param[in]	guard_transaction		bool
+ *  
+ */
 PEP_STATUS set_identity_entry(PEP_SESSION session, pEp_identity* identity,
                               bool guard_transaction) {
     return set_or_update_with_identity(session, identity,
@@ -3444,6 +3538,17 @@ pEp_free:
     return status;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       update_pEp_user_trust_vals()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  @param[in]	*user		pEp_identity
+ *  
+ */
 PEP_STATUS update_pEp_user_trust_vals(PEP_SESSION session,
                                       pEp_identity* user) {
     if (!user->user_id)
@@ -3588,6 +3693,17 @@ PEP_STATUS exists_person(PEP_SESSION session, pEp_identity* identity,
     return status;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       delete_person()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  @param[in]	*user_id		constchar
+ *  
+ */
 PEP_STATUS delete_person(PEP_SESSION session, const char* user_id) {
 
     if (!session || EMPTYSTR(user_id))
@@ -3939,6 +4055,18 @@ DYNAMIC_API PEP_STATUS set_ident_enc_format(
     return PEP_STATUS_OK;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       get_trust_by_userid()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  @param[in]	*user_id		constchar
+ *  @param[in]	**trust_list		labeled_int_list_t
+ *  
+ */
 PEP_STATUS get_trust_by_userid(PEP_SESSION session, const char* user_id,
                                            labeled_int_list_t** trust_list)
 {
@@ -3969,6 +4097,17 @@ PEP_STATUS get_trust_by_userid(PEP_SESSION session, const char* user_id,
     return PEP_STATUS_OK;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       reconcile_trust()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	t_old		PEP_comm_type
+ *  @param[in]	t_new		PEP_comm_type
+ *  
+ */
 PEP_comm_type reconcile_trust(PEP_comm_type t_old, PEP_comm_type t_new) {
     switch (t_new) {
         case PEP_ct_mistrusted:
@@ -3998,6 +4137,18 @@ PEP_comm_type reconcile_trust(PEP_comm_type t_old, PEP_comm_type t_new) {
     return result;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       reconcile_pEp_status()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  @param[in]	*old_uid		constchar
+ *  @param[in]	*new_uid		constchar
+ *  
+ */
 PEP_STATUS reconcile_pEp_status(PEP_SESSION session, const char* old_uid, 
                                 const char* new_uid) {
     PEP_STATUS status = PEP_STATUS_OK;
@@ -4020,6 +4171,18 @@ pEp_free:
     return status;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       reconcile_usernames()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*old_name		constchar
+ *  @param[in]	*new_name		constchar
+ *  @param[in]	*address		constchar
+ *  
+ */
 const char* reconcile_usernames(const char* old_name, const char* new_name, 
                                 const char* address) {
     if (EMPTYSTR(old_name)) {
@@ -4035,6 +4198,18 @@ const char* reconcile_usernames(const char* old_name, const char* new_name,
     return new_name;        
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       reconcile_default_keys()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  @param[in]	*old_ident		pEp_identity
+ *  @param[in]	*new_ident		pEp_identity
+ *  
+ */
 PEP_STATUS reconcile_default_keys(PEP_SESSION session, pEp_identity* old_ident,
                                   pEp_identity* new_ident) {
     PEP_STATUS status = PEP_STATUS_OK;
@@ -4087,6 +4262,17 @@ PEP_STATUS reconcile_default_keys(PEP_SESSION session, pEp_identity* old_ident,
     return status;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       reconcile_language()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*old_ident		pEp_identity
+ *  @param[in]	*new_ident		pEp_identity
+ *  
+ */
 void reconcile_language(pEp_identity* old_ident,
                         pEp_identity* new_ident) {
     if (new_ident->lang[0] == 0) {
@@ -4099,6 +4285,18 @@ void reconcile_language(pEp_identity* old_ident,
 }
 
 // ONLY CALL THIS IF BOTH IDs ARE IN THE PERSON DB, FOOL! </Mr_T>
+/**
+ *  @internal
+ *  
+ *  <!--       merge_records()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  @param[in]	*old_uid		constchar
+ *  @param[in]	*new_uid		constchar
+ *  
+ */
 PEP_STATUS merge_records(PEP_SESSION session, const char* old_uid,
                          const char* new_uid) {
     PEP_STATUS status = PEP_STATUS_OK;
@@ -4525,6 +4723,16 @@ DYNAMIC_API PEP_STATUS least_trust(
     return status;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       sanitize_pgp_filename()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*filename		char
+ *  
+ */
 static void sanitize_pgp_filename(char *filename)
 {
     for (int i=0; filename[i]; ++i) {
@@ -4872,6 +5080,16 @@ DYNAMIC_API PEP_STATUS config_cipher_suite(PEP_SESSION session,
     return session->cryptotech[PEP_crypt_OpenPGP].config_cipher_suite(session, suite);
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       _clean_log_value()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*text		char
+ *  
+ */
 static void _clean_log_value(char *text)
 {
     if (text) {
@@ -5150,6 +5368,17 @@ static PEP_STATUS _get_sequence_value(PEP_SESSION session, const char *name,
     return status;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       _increment_sequence_value()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  @param[in]	*name		constchar
+ *  
+ */
 static PEP_STATUS _increment_sequence_value(PEP_SESSION session,
         const char *name)
 {

src/pgp_sequoia.c

@@ -133,6 +133,18 @@ int sq_sql_trace_callback (unsigned trace_constant,
  * if both s1 < MUL_NO_OVERFLOW and s2 < MUL_NO_OVERFLOW
  */
 #define PEP_MUL_NO_OVERFLOW ((size_t)1 << (sizeof(size_t) * 4))
+/**
+ *  @internal
+ *  
+ *  <!--       _pEp_reallocarray()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*optr		void
+ *  @param[in]	nmemb		size_t
+ *  @param[in]	size		size_t
+ *  
+ */
 static void* _pEp_reallocarray(void *optr, size_t nmemb, size_t size)
 {
     if ((nmemb >= PEP_MUL_NO_OVERFLOW || size >= PEP_MUL_NO_OVERFLOW) &&
@@ -169,6 +181,16 @@ PEP_STATUS pgp_config_cipher_suite(PEP_SESSION session,
     }
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       cipher_suite()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	suite		PEP_CIPHER_SUITE
+ *  
+ */
 static pgp_cert_cipher_suite_t cipher_suite(PEP_CIPHER_SUITE suite)
 {
     switch (suite) {
@@ -190,6 +212,20 @@ static pgp_cert_cipher_suite_t cipher_suite(PEP_CIPHER_SUITE suite)
     }
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       email_cmp()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*cookie		void
+ *  @param[in]	a_len		int
+ *  @param[in]	*a		constvoid
+ *  @param[in]	b_len		int
+ *  @param[in]	*b		constvoid
+ *  
+ */
 int email_cmp(void *cookie, int a_len, const void *a, int b_len, const void *b)
 {
     pgp_packet_t a_userid = pgp_user_id_from_raw (a, a_len);
@@ -234,6 +270,18 @@ int email_cmp(void *cookie, int a_len, const void *a, int b_len, const void *b)
     return result;
 }
 
+/**
+ *  @internal
+ *  
+ *  <!--       _pgp_get_decrypted_key()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	session		PEP_SESSION
+ *  @param[in]	iter		pgp_cert_valid_key_iter_t
+ *  @param[in]	*decrypted_key		pgp_key_t
+ *  
+ */
 static PEP_STATUS _pgp_get_decrypted_key(PEP_SESSION session,
                                          pgp_cert_valid_key_iter_t iter,
                                          pgp_key_t* decrypted_key) {
@@ -602,6 +650,16 @@ void pgp_release(PEP_SESSION session, bool out_last)
 // fingerprint doesn't contain any white space.
 //
 // This function does *not* consume fpr.
+/**
+ *  @internal
+ *  
+ *  <!--       pgp_fingerprint_canonicalize()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	*		constchar
+ *  
+ */
 static char *pgp_fingerprint_canonicalize(const char *) __attribute__((nonnull));
 static char *pgp_fingerprint_canonicalize(const char *fpr)
 {
@@ -698,6 +756,20 @@ static PEP_STATUS key_loadn(PEP_SESSION session, sqlite3_stmt *stmt,
 // Returns the certificate identified by the provided fingerprint.
 //
 // This function only matches on the primary key!
+/**
+ *  @internal
+ *  
+ *  <!--       cert_find()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	PEP_SESSION		PEP_SESSION
+ *  @param[in]	pgp_fingerprint_t		pgp_fingerprint_t
+ *  @param[in]	int		int
+ *  @param[in]	*		pgp_cert_t
+ *  @param[in]	*		int
+ *  
+ */
 static PEP_STATUS cert_find(PEP_SESSION, pgp_fingerprint_t, int, pgp_cert_t *, int *)
     __attribute__((nonnull(1, 2)));
 static PEP_STATUS cert_find(PEP_SESSION session,
@@ -734,6 +806,20 @@ static PEP_STATUS cert_find(PEP_SESSION session,
 //
 // If private_only is set, this will only consider certificates with some
 // secret key material.
+/**
+ *  @internal
+ *  
+ *  <!--       cert_find_by_keyid_hex()       -->
+ *  
+ *  @brief			TODO
+ *  
+ *  @param[in]	PEP_SESSION		PEP_SESSION
+ *  @param[in]	*		constchar
+ *  @param[in]	int		int
+ *  @param[in]	*		pgp_cert_t
+ *  @param[in]	*		int
+ *  
+ */
 static PEP_STATUS cert_find_by_keyid_hex(PEP_SESSION, const char *, int, pgp_cert_t *, int *)
   __attribute__((nonnull(1, 2)));
 static PEP_STATUS cert_find_by_keyid_hex(
@@ -757,6 +843,20 @@ static PEP_STATUS cert_find_by_keyid_hex(
 }
 
 // See cert_find_by_keyid_hex.