Resolving some doxygen issues

src/base64.c

@@ -14,6 +14,13 @@
 #include "platform.h"
 #include "base64.h"
 
+/**
+ * <!-- translate_char_to_bits() -->
+ * @brief convert ascii value to corresponding base64 digit value
+ * @param[in] input char to translate
+ * @retval base64 value
+ * @retval -1 if char is not a base64 encoding char.
+ */
 static char translate_char_to_bits(char input) {
     if (input >= 65 && input <= 90)
         return input - 65;
@@ -134,19 +141,11 @@ char next_char(const char** input_ptr, const char* end) {
     return this_ch;
 }
 
-/**
+/*
  *  @internal
  *  
  *  <!--       base64_str_to_binary_blob()       -->
- *  
- *  @brief      converts base64 to a binary blob, putting 4 characters into
- *              3 output bytes, returning a pointer to a bloblist containing
- *              the binary blob.
- *  
- *  @param[in]  *input    input as C string
- *  @param[in]  int       length of C string
- *  
- *  @retval     pointer to bloblist, or NULL on failure  
+ *  documented in base64.h  
  */
 bloblist_t* base64_str_to_binary_blob(const char* input, int length) {
     if (length == 0)

src/base64.h

@@ -21,10 +21,15 @@ extern "C" {
  *
  *  @brief   Decode a base64 string and return binary format
  *
+ *  converts base64 to a binary blob, putting 4 characters into
+ *              3 output bytes, returning a pointer to a bloblist containing
+ *              the binary blob.
+ *
  *  @param[in]   input            base64 string
  *  @param[in]   length           string length
  *
- *  @retval     decoded binary blob of input string
+ *  @retval     pointer to decoded binary blob of input string
+ *  @retval     NULL on failure  
  *
  */
 bloblist_t* base64_str_to_binary_blob(const char* input, int length);

src/baseprotocol.c

@@ -4,7 +4,7 @@
  *           decoration, payload, extraction, etc.). These are used for
  *           protocol messages in, for example, key sync and key reset.
  *           The payloads of these messages are, in general, not human-readable.
- *           @see baseprotocol.h
+ * @see      baseprotocol.h
  * @license  GNU General Public License 3.0 - see LICENSE.txt
 */
 
@@ -12,6 +12,14 @@
 #include "message_api.h"
 #include "baseprotocol.h"
 
+/**
+ * @internal
+ * @brief Convert base protocol type from enum to MIME type string
+ * @param[in] type	base_protocol_type
+ * @param[out] type_str	char**
+ * @retval PEP_STATUS_OK
+ * @retval PEP_ILLEGAL_VALUE on illegal value of `type`
+ */
 static PEP_STATUS _get_base_protocol_type_str(base_protocol_type type, const char** type_str) {
     *type_str = NULL;
     switch(type) {

src/bloblist.c

@@ -13,6 +13,17 @@
 #include "platform.h"
 #include "bloblist.h"
 
+/**
+ * @internal
+ * @brief TODO
+ * @param[out] bloblist
+ * @param[in] blob
+ * @param[in] size size of blob
+ * @param[in] mime_type
+ * @param[in] filename
+ * @retval true on success
+ * @retval false on failure
+ */
 static bool set_blob_data(bloblist_t* bloblist, char* blob, size_t size, const char* mime_type,
         const char* filename)
 {

src/bloblist.h

@@ -187,6 +187,14 @@ DYNAMIC_API void set_blob_disposition(bloblist_t* blob,
  */
 DYNAMIC_API bloblist_t* bloblist_join(bloblist_t* first, bloblist_t* second);
 
+/**
+ * <!-- find_blob_by_URI() -->
+ * @brief Search bloblist for member with member->filename == uri
+ * @param[in] bloblist bloblist_t*
+ * @param[in] uri char*
+ * @retval pointer to member of bloblist
+ * @retval NULL on failure
+ */
 bloblist_t* find_blob_by_URI(bloblist_t* bloblist, const char* uri);
     
 #ifdef __cplusplus

src/internal_format.c

@@ -9,6 +9,24 @@
 #include "pEp_internal.h"
 #include "internal_format.h"
 
+/**
+ * <!-- _internal_message_type -->
+ * @brief Definition of internal message format
+ * @see https://dev.pep.foundation/Engine/ElevatedAttachments#internal-message-format
+ * 
+ * @par Key material
+ * Key material is encoded with 0 ‘K’ subtype 0 followed by the binary representation of the .value of the attachment for transports.
+ * 
+ * @par p≡p Sync
+ * A p≡p Sync message is encoded with 0 ‘S’ subtype 0 followed by the binary representation of the .value of the attachment.
+ * 
+ * @par p≡p Distribution
+ * A p≡p Distribution message is encoded with 0 ‘D’ subtype 0 followed by the binary representation of the .value of the attachment.
+ * 
+ * @par Authentication material
+ * Key material is encoded with 0 ‘A’ subtype 0 followed by the binary representation of the .value of the attachment.
+ * 
+ */
 static struct _internal_message_type {
     char type;
     char subtype;

src/pEpEngine.h

@@ -511,7 +511,7 @@ typedef enum {
  *  @brief Cipher suite being used when encrypting
  *  
  *  @param[in]   session         session handle
- *  @param[in]   cipher_suite    cipher suite to use
+ *  @param[in]   suite    cipher suite to use
  *  
  *  @retval PEP_STATUS_OK           cipher suite configured
  *  @retval PEP_CANNOT_CONFIG       configuration failed; falling back to default
@@ -535,7 +535,7 @@ DYNAMIC_API PEP_STATUS config_cipher_suite(PEP_SESSION session,
  *  @param[in]     csize           size of cipher text
  *  @param[in]     dsigtext        if extant, *detached* signature text for this
  *                                 message (or NULL if not)
- *  @param[in]     dsize           size of *detached* signature text for this
+ *  @param[in]     dsigsize        size of *detached* signature text for this
  *                                 message (0, if no detached sig exists)
  *  @param[out]    ptext           pointer to internal buffer with plain text
  *  @param[out]    psize           size of plain text

src/transport.h

@@ -17,9 +17,7 @@ extern "C" {
 
 /**
  *  @enum    PEP_transport_id
- *  
  *  @brief    TODO
- *  
  */
 typedef enum _PEP_transport_id {
     /// auto transport chooses transport per message automatically
@@ -41,10 +39,11 @@ typedef struct _transport_config {
     // in C++ this must be POD
 } transport_config_t;
 
-// transports are delivering the transport status code
-// this is defined here:
-// https://dev.pep.foundation/Engine/TransportStatusCode
-
+/// @brief transports are delivering the transport status code
+///
+/// this is defined here:
+/// https://dev.pep.foundation/Engine/TransportStatusCode
+/// @see https://dev.pep.foundation/Engine/TransportStatusCode
 typedef struct _PEP_transport_t PEP_transport_t;
 
 // functions offered by transport