Browse Source

more doxygen comments

pull/22/head
Sofia Balicka 1 year ago
parent
commit
dfdee25ff4
8 changed files with 114 additions and 53 deletions
  1. +31
    -20
      src/base64.c
  2. +9
    -5
      src/baseprotocol.c
  3. +12
    -3
      src/baseprotocol.h
  4. +6
    -5
      src/bloblist.c
  5. +5
    -5
      src/cryptotech.c
  6. +5
    -5
      src/email.c
  7. +40
    -5
      src/etpan_mime.c
  8. +6
    -5
      src/growing_buf.c

+ 31
- 20
src/base64.c View File

@ -1,8 +1,10 @@
/** @file */
/** @brief File description for doxygen missing. FIXME */
// This file is under GNU General Public License 3.0
// see LICENSE.txt
/**
* @file base64.c
* @brief Convert base64 to a binary blob - this is the implementation of
* a convenience function used mainly to convert keys which are
* base64 rather than radix64 (i.e. PGP armoured) encoded
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#include <stdbool.h>
#include <stdlib.h>
@ -33,9 +35,11 @@ static char translate_char_to_bits(char input) {
*
* <!-- _is_whitespace() -->
*
* @brief TODO
* @brief checks if a character is a whitespace character
* end returns true if so, false otherwise
*
* @param[in] in constchar
* @param[in] in char to be checked
* @retval bool true if whitespace, false otherwise
*
*/
static bool _is_whitespace(const char in) {
@ -55,10 +59,12 @@ static bool _is_whitespace(const char in) {
*
* <!-- subtract_whitespace() -->
*
* @brief TODO
* @brief returns the lenght of the C string
* not counting whitespaces
*
* @param[in] *input constchar
* @param[in] length int
* @param[in] *input C string
* @param[in] length length of the C string
* @retval size_t actual size of string without whitespaces
*
*/
static size_t subtract_whitespace(const char* input, int length) {
@ -77,10 +83,11 @@ static size_t subtract_whitespace(const char* input, int length) {
*
* <!-- trim_end() -->
*
* @brief TODO
* @brief determine length of C string without
* trailing whitespace characters
*
* @param[in] *input constchar
* @param[in] *length int
* @param[in] *input C string to check
* @param[in,out] *length returns the resulting lenght
*
*/
static void trim_end(const char* input, int* length) {
@ -102,10 +109,12 @@ static void trim_end(const char* input, int* length) {
*
* <!-- next_char() -->
*
* @brief TODO
* @brief returns the next non-whitespace character in a C string
*
* @param[in] **input_ptr constchar
* @param[in] *end constchar
* @param[in] **input_ptr pointer to C string
* @param[in] *end pointer to last char of input string
*
* @retval char next non-whitespace character
*
*/
char next_char(const char** input_ptr, const char* end) {
@ -125,17 +134,19 @@ char next_char(const char** input_ptr, const char* end) {
return this_ch;
}
// 4 chars = 3 output bytes
/**
* @internal
*
* <!-- base64_str_to_binary_blob() -->
*
* @brief TODO
* @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 const char
* @param[in] length int
* @param[in] *input input as C string
* @param[in] int length of C string
*
* @retval pointer to bloblist, or NULL on failure
*/
bloblist_t* base64_str_to_binary_blob(const char* input, int length) {
if (length == 0)


+ 9
- 5
src/baseprotocol.c View File

@ -1,8 +1,12 @@
/** @file */
/** @brief File description for doxygen missing. FIXME */
// This file is under GNU General Public License 3.0
// see LICENSE.txt
/**
* @file baseprotocol.c
* @brief Implementation of basic functions for administrative pEp messages (preparation,
* 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
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#include "pEp_internal.h"
#include "message_api.h"


+ 12
- 3
src/baseprotocol.h View File

@ -79,7 +79,9 @@ PEP_STATUS base_decorate_message(
* @param[out] result returned message with payload on success
*
* @retval PEP_STATUS_OK on success
* @retval error_status on failure
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval PEP_ILLEGAL_VALUE illegal or missing parameter values
* @retval any other value on failure
*
* @ownership
* - On (and only on) success, ownership of payload is assigned to the result structure
@ -113,8 +115,10 @@ PEP_STATUS base_prepare_message(
* @param[out] fpr if message was correctly signed then fpr of signature's
* key, otherwise NULL
*
* @retval PEP_STATUS_OK if no error occurred, whether or not sync message was found
* @retval error_status any other value on error
* @retval PEP_STATUS_OK jif no error occurred, whether or not sync message was found
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval PEP_ILLEGAL_VALUE illegal or missing parameter values
* @retval error_status any other value on error
*
* @ownership
* - Payload may point to msg attachment, but the ownership does not change
@ -151,6 +155,11 @@ PEP_STATUS base_extract_message(
* @param[in] fpr optional key to sign or NULL
* @param[out] result returned message with payload on success
*
* @retval PEP_STATUS_OK if no error occurred, whether or not sync message was found
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval PEP_ILLEGAL_VALUE illegal or missing parameter values
* @retval error_status any other value on error
*
* @ownership
* - On (and only on) success, ownership of payload is assigned to the result structure
* - Ownership of the result goes to the caller


+ 6
- 5
src/bloblist.c View File

@ -1,8 +1,9 @@
/** @file */
/** @brief File description for doxygen missing. FIXME */
// This file is under GNU General Public License 3.0
// see LICENSE.txt
/**
* @file bloblist.c
* @brief implemantation of functions for list structure to hold data of unspecified
* format (hence, "blob list"); can contain addition format information in structure's mime info
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#include <stdbool.h>
#include <stdlib.h>


+ 5
- 5
src/cryptotech.c View File

@ -1,8 +1,8 @@
/** @file */
/** @brief File description for doxygen missing. FIXME */
// This file is under GNU General Public License 3.0
// see LICENSE.txt
/**
* @file cryptotech.c
* @brief File description for doxygen missing. FIXME
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#include "pEp_internal.h"


+ 5
- 5
src/email.c View File

@ -1,8 +1,8 @@
/** @file */
/** @brief File description for doxygen missing. FIXME */
// This file is under GNU General Public License 3.0
// see LICENSE.txt
/**
* @file email.c
* @brief File description for doxygen missing. FIXME
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#include "email.h"


+ 40
- 5
src/etpan_mime.c View File

@ -1,8 +1,8 @@
/** @file */
/** @brief File description for doxygen missing. FIXME */
// This file is under GNU General Public License 3.0
// see LICENSE.txt
/**
* @file etpan_mime.c
* @brief File description for doxygen missing. FIXME
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#include "etpan_mime.h"
#ifndef mailmime_param_new_with_data
@ -1080,6 +1080,9 @@ static PEP_STATUS interpret_MIME(struct mailmime *mime,
* @param[in] *mime structmailmime
* @param[in] **mimetext char
*
* @retval PEP_STATUS_OK
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*/
static PEP_STATUS render_mime(struct mailmime *mime, char **mimetext)
{
@ -1140,6 +1143,10 @@ pEp_error:
* @param[in] *blob bloblist_t
* @param[in] **result structmailmime
* @param[in] is_nf_message_attachment bool
*
* @retval PEP_STATUS_OK
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*
*/
static PEP_STATUS mime_attachment(
@ -1211,6 +1218,9 @@ enomem:
* @param[in] *attachments bloblist_t
* @param[in] **result structmailmime
*
* @retval PEP_STATUS_OK
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*/
static PEP_STATUS mime_html_text(
const char *plaintext,
@ -1596,6 +1606,9 @@ static clist * stringlist_to_clist(stringlist_t *sl, bool transport_encode)
* @param[in] *msg constmessage
* @param[in] **result structmailimf_fields
*
* @retval PEP_STATUS_OK
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*/
static PEP_STATUS build_fields(const message *msg, struct mailimf_fields **result)
{
@ -1920,6 +1933,9 @@ static pEp_rid_list_t* choose_resource_id(pEp_rid_list_t* rid_list) {
* @param[in] **result structmailmime
* @param[in] has_pEp_msg_attachment bool
*
* @retval PEP_STATUS_OK
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*/
static PEP_STATUS mime_encode_message_plain(
const message *msg,
@ -2086,6 +2102,10 @@ pEp_error:
* @param[in] *msg constmessage
* @param[in] omit_fields bool
* @param[in] **result structmailmime
*
* @retval PEP_STATUS_OK
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*
*/
static PEP_STATUS mime_encode_message_PGP_MIME(
@ -2454,6 +2474,9 @@ enomem:
* @param[in] *msg message
* @param[in] *fieldlist clist
*
* @retval PEP_STATUS_OK
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*/
static PEP_STATUS read_fields(message *msg, clist *fieldlist)
{
@ -2676,6 +2699,10 @@ pEp_error:
* @param[in] **longmsg char
* @param[in] *size size_t
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal or missing parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*/
static PEP_STATUS interpret_body(struct mailmime *part, char **longmsg, size_t *size)
{
@ -2815,6 +2842,10 @@ static PEP_STATUS interpret_protected_headers(
*
* @param[in] *mime structmailmime
* @param[in] *msg message
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal or missing parameter values
* @retval any other value on error
*
*/
static PEP_STATUS process_multipart_related(struct mailmime *mime,
@ -2914,6 +2945,10 @@ static bool _is_marked_as_attachment(struct mailmime_fields *fields)
* @param[in] *msg message
* @param[in] *has_possible_pEp_msg bool
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal or missing parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*/
static PEP_STATUS interpret_MIME(
struct mailmime *mime,


+ 6
- 5
src/growing_buf.c View File

@ -1,8 +1,9 @@
/** @file */
/** @brief File description for doxygen missing. FIXME */
// This file is under GNU General Public License 3.0
// see LICENSE.txt
/*
* @file growing_buf.c
* @brief implementation of growing buffer, which is needed by the ASN.1 implementation
* i.e. for encoding to XER
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#include "pEp_internal.h"
#include "growing_buf.h"


Loading…
Cancel
Save