enum doc placeholders

src/baseprotocol.h

@@ -13,6 +13,12 @@ extern "C" {
 #endif
 
 
+/**
+ *  @enum	base_protocol_type
+ *  
+ *  @brief	TODO
+ *  
+ */
 typedef enum _base_protocol_type {
     BASE_SIGN = 0,
 

src/bloblist.h

@@ -16,6 +16,12 @@
 extern "C" {
 #endif
 
+/**
+ *  @enum	content_disposition_type
+ *  
+ *  @brief	TODO
+ *  
+ */
 typedef enum {
     PEP_CONTENT_DISP_ATTACHMENT = 0,
     PEP_CONTENT_DISP_INLINE = 1,

src/cryptotech.h

@@ -10,6 +10,12 @@
 #include "pEpEngine.h"
 #include "bloblist.h"
 
+/**
+ *  @enum	PEP_cryptotech
+ *  
+ *  @brief	TODO
+ *  
+ */
 typedef enum _PEP_cryptotech {
     PEP_crypt_none = 0,
     PEP_crypt_OpenPGP,

src/fsm_common.h

@@ -14,6 +14,12 @@ extern "C" {
 
 // error values
 
+/**
+ *  @enum	fsm_error
+ *  
+ *  @brief	TODO
+ *  
+ */
 typedef enum _fsm_error {
     // these error values are corresponding to
     // PEP_SYNC_STATEMACHINE_ERROR - value

src/message.h

@@ -22,12 +22,24 @@ extern "C" {
 #endif
 
 
+/**
+ *  @enum	PEP_text_format
+ *  
+ *  @brief	TODO
+ *  
+ */
 typedef enum _PEP_text_format {
     PEP_text_format_plain = 0,
     PEP_text_format_html,
     PEP_text_format_other = 0xff
 } PEP_text_format;
 
+/**
+ *  @enum	PEP_msg_direction
+ *  
+ *  @brief	TODO
+ *  
+ */
 typedef enum _PEP_msg_direction {
     PEP_dir_incoming = 0,
     PEP_dir_outgoing

src/message_api.h

@@ -57,6 +57,12 @@ PEP_cryptotech determine_encryption_format(message *msg);
  */
 void add_opt_field(message *msg, const char *name, const char *value);
 
+/**
+ *  @enum	PEP_encrypt_flags
+ *  
+ *  @brief	TODO
+ *  
+ */
 typedef enum _PEP_encrypt_flags {
     // "default" means whatever the default behaviour for the function is.
     PEP_encrypt_flag_default = 0x0,
@@ -84,6 +90,12 @@ typedef enum _PEP_encrypt_flags {
 
 typedef unsigned int PEP_encrypt_flags_t;
 
+/**
+ *  @enum	message_wrap_type
+ *  
+ *  @brief	TODO
+ *  
+ */
 typedef enum _message_wrap_type {
     PEP_message_unwrapped,  // 1.0 or anything we don't wrap    
     PEP_message_default,    // typical inner/outer message 2.0
@@ -145,7 +157,7 @@ DYNAMIC_API PEP_STATUS encrypt_message(
  *  @param[in]     src           message to encrypt
  *  @param[out]    dst           pointer to new encrypted message or NULL if no
  *                               encryption could take place
- *                               to_fpr              fingerprint of the recipient key to which the private key
+ *  @param[in]     to_fpr        fingerprint of the recipient key to which the private key
  *                               should be encrypted
  *  @param[in]     enc_format    encrypted format
  *  @param[in]     flags         flags to set special encryption features
@@ -210,6 +222,12 @@ DYNAMIC_API PEP_STATUS encrypt_message_for_self(
         PEP_encrypt_flags_t flags
     );
 
+/**
+ *  @enum	PEP_rating
+ *  
+ *  @brief	TODO
+ *  
+ */
 typedef enum _PEP_rating {
     PEP_rating_undefined = 0,
 
@@ -238,6 +256,12 @@ typedef enum _PEP_rating {
     PEP_rating_under_attack = -3
 } PEP_rating;
 
+/**
+ *  @enum	PEP_color
+ *  
+ *  @brief	TODO
+ *  
+ */
 typedef enum _PEP_color {
     PEP_color_no_color = 0,
     PEP_color_yellow,
@@ -257,6 +281,12 @@ typedef enum _PEP_color {
  */
 DYNAMIC_API PEP_color color_from_rating(PEP_rating rating);
 
+/**
+ *  @enum	PEP_decrypt_flags
+ *  
+ *  @brief	TODO
+ *  
+ */
 typedef enum _PEP_decrypt_flags {
     PEP_decrypt_flag_own_private_key = 0x1,
     PEP_decrypt_flag_consume = 0x2,
@@ -621,18 +651,15 @@ DYNAMIC_API PEP_STATUS get_key_rating_for_user(
 
 DYNAMIC_API PEP_rating rating_from_comm_type(PEP_comm_type ct);
 
-
-// this is the internal function to be used by asynchronous network protocol
-// implementations
-//
-// this function is calling messageToSend(NULL) in case there is a missing or wrong passphrase
-//
-// do not use it in adapters
-
 /**
+ *  @internal
+ * 
  *  <!--       try_encrypt_message()       -->
  *  
- *  @brief			TODO
+ *  @brief This is the internal version of encrypt_message() 
+ *         to be used by asynchronous network protocol
+ *         implementations. This function is calls messageToSend(NULL) 
+ *         in case there is a missing or wrong passphrase.
  *  
  *  @param[in]	session		PEP_SESSION
  *  @param[in]	*src		message
@@ -641,6 +668,9 @@ DYNAMIC_API PEP_rating rating_from_comm_type(PEP_comm_type ct);
  *  @param[in]	enc_format		PEP_enc_format
  *  @param[in]	flags		PEP_encrypt_flags_t
  *  
+ *  @warning    Do NOT use this function in adapters.
+ * 
+ *  @todo KB: line up with the try_base_blahblah docs
  */
 PEP_STATUS try_encrypt_message(
         PEP_SESSION session,

src/pEpEngine.h

@@ -43,6 +43,12 @@ extern "C" {
 struct _pEpSession;
 typedef struct _pEpSession * PEP_SESSION;
 
+/**
+ *  @enum	PEP_STATUS
+ *  
+ *  @brief	TODO
+ *  
+ */
 typedef enum {
     PEP_STATUS_OK                                   = 0,
 
@@ -154,6 +160,12 @@ typedef enum {
     PEP_VERSION_MISMATCH                            = -7,
 } PEP_STATUS;
 
+/**
+ *  @enum	PEP_enc_format
+ *  
+ *  @brief	TODO
+ *  
+ */
 typedef enum _PEP_enc_format {
     PEP_enc_none = 0,                       // message is not encrypted
     PEP_enc_pieces = 1,                     // inline PGP + PGP extensions, was removed
@@ -358,6 +370,12 @@ DYNAMIC_API void config_use_only_own_private_keys(PEP_SESSION session, bool enab
 DYNAMIC_API void config_service_log(PEP_SESSION session, bool enable);
 
 
+/**
+ *  @enum	PEP_CIPHER_SUITE
+ *  
+ *  @brief	TODO
+ *  
+ */
 typedef enum {
     PEP_CIPHER_SUITE_DEFAULT = 0,
     PEP_CIPHER_SUITE_CV25519 = 1,
@@ -636,6 +654,12 @@ DYNAMIC_API PEP_STATUS trustwords(
 
 // TODO: increase versions in pEp.asn1 if rating changes
 
+/**
+ *  @enum	PEP_comm_type
+ *  
+ *  @brief	TODO
+ *  
+ */
 typedef enum _PEP_comm_type {
     PEP_ct_unknown = 0,
 
@@ -698,6 +722,12 @@ typedef enum _PEP_comm_type {
     PEP_ct_pEp = 0xff
 } PEP_comm_type;
 
+/**
+ *  @enum	identity_flags
+ *  
+ *  @brief	TODO
+ *  
+ */
 typedef enum _identity_flags {
     // the first octet flags are app defined settings
     PEP_idf_not_for_sync = 0x0001,   // don't use this identity for sync

src/pEp_internal.h

@@ -293,6 +293,7 @@ struct _pEpSession {
  *  
  */
 PEP_STATUS init_transport_system(PEP_SESSION session, bool in_first);
+
 /**
  *  <!--       release_transport_system()       -->
  *  
@@ -304,8 +305,9 @@ PEP_STATUS init_transport_system(PEP_SESSION session, bool in_first);
  */
 void release_transport_system(PEP_SESSION session, bool out_last);
 
-/* NOT to be exposed to the outside!!! */
 /**
+ *  @internal
+ * 
  *  <!--       encrypt_only()       -->
  *  
  *  @brief			TODO
@@ -317,6 +319,7 @@ void release_transport_system(PEP_SESSION session, bool out_last);
  *  @param[in]	**ctext		char
  *  @param[in]	*csize		size_t
  *  
+ *  @warning    NOT to be exposed to the outside!!!!!
  */
 PEP_STATUS encrypt_only(
         PEP_SESSION session, const stringlist_t *keylist, const char *ptext,
@@ -358,6 +361,12 @@ void decorate_message(
 }
 #endif
 
+/**
+ *  @enum	normalize_hex_res_t
+ *  
+ *  @brief	TODO
+ *  
+ */
 typedef enum _normalize_hex_rest_t {
     accept_hex,
     ignore_hex,
@@ -511,13 +520,21 @@ static inline int _same_fpr(
 // for comparing two full strings. If charstr's length is different from bytestr_size,
 // we'll return a non-zero value.
 /**
+ *  @internal
+ * 
  *  <!--       _unsigned_signed_strcmp()       -->
  *  
- *  @brief			TODO
- *  
- *  @param[in]	*bytestr		constunsignedchar
- *  @param[in]	*charstr		constchar
- *  @param[in]	bytestr_size		int
+ *  @brief      Compare an unsigned sequence of bytes with the input string.
+ *              This is really only intended for comparing two full strings. 
+ *              If charstr's length is different from bytestr_size,
+ *              we'll return a non-zero value.
+ * 
+ *  @param[in]	bytestr		    byte string (unsigned char data)
+ *  @param[in]	charstr		    character string (NUL-terminated)
+ *  @param[in]	bytestr_size    length of byte string passed in
+ * 
+ *  @retval     0           if equal
+ *  @retval     non-zero    if not equal
  *  
  */
 static inline int _unsigned_signed_strcmp(const unsigned char* bytestr, const char* charstr, int bytestr_size) {

src/resource_id.h

@@ -7,6 +7,12 @@
 #pragma once
 
 /* structs to contain info about parsed resource ids (filenames, uids) */
+/**
+ *  @enum	pEp_resource_id_type
+ *  
+ *  @brief	TODO
+ *  
+ */
 typedef enum _resource_id_type {
     PEP_RID_FILENAME,
     PEP_RID_CID

src/sync_api.h

@@ -15,6 +15,12 @@ extern "C" {
 #endif
 
 
+/**
+ *  @enum	sync_handshake_signal
+ *  
+ *  @brief	TODO
+ *  
+ */
 typedef enum _sync_handshake_signal {
     SYNC_NOTIFY_UNDEFINED = 0,
 
@@ -74,6 +80,12 @@ typedef PEP_STATUS (*notifyHandshake_t)(
         sync_handshake_signal signal
     );
 
+/**
+ *  @enum	sync_handshake_result
+ *  
+ *  @brief	TODO
+ *  
+ */
 typedef enum _sync_handshake_result {
     SYNC_HANDSHAKE_CANCEL = -1,
     SYNC_HANDSHAKE_ACCEPTED = 0,

src/transport.h

@@ -13,6 +13,12 @@
 extern "C" {
 #endif
 
+/**
+ *  @enum	PEP_transports
+ *  
+ *  @brief	TODO
+ *  
+ */
 typedef enum _PEP_transports {
     // auto transport chooses transport per message automatically
     PEP_trans_auto = 0,