From f6bacc5058d8049a44f25fcc7a931227ddcfb65e Mon Sep 17 00:00:00 2001 From: Markus Teich Date: Sun, 19 Jun 2016 23:21:01 +0200 Subject: [PATCH] some doxygen fixes --- brandt.c | 2 +- brandt.h | 34 ++++++++--------- crypto.c | 37 ++++++++++--------- doc/Makefile.am | 2 +- doc/brandt.doxy | 2 +- test_crypto.c | 4 +- uncrustify/file_header | 2 +- util.c | 84 ++++++++++++++++++++++-------------------- 8 files changed, 86 insertions(+), 81 deletions(-) diff --git a/brandt.c b/brandt.c index 30cfd92..6a9f7c8 100644 --- a/brandt.c +++ b/brandt.c @@ -16,7 +16,7 @@ /** * @file brandt.c - * @brief TODO + * @brief \todo */ #include diff --git a/brandt.h b/brandt.h index b7ebf5b..0e41021 100644 --- a/brandt.h +++ b/brandt.h @@ -26,7 +26,7 @@ #include /** - * FIXME. + * \todo. */ struct BRANDT_Auction; @@ -34,7 +34,7 @@ struct BRANDT_Auction; * Functions of this type are called by libbrandt to broadcast messages to the * blackboard of a specific auction. * - * TODO: how must the message be handled? (encryption, auth, reliability, …) + * \todo: how must the message be handled? (encryption, auth, reliability, …) * * @param[in] auction_closure Closure pointer representing the respective * auction. This is the Pointer given to BRANDT_join(). @@ -53,7 +53,7 @@ typedef int * Functions of this type are called by libbrandt to unicast messages to the * seller of a specific auction. * - * TODO: how must the message be handled? (encryption, auth, reliability, …) + * \todo: how must the message be handled? (encryption, auth, reliability, …) * * @param[in] auction_closure Closure pointer representing the respective * auction. This is the Pointer given to BRANDT_join(). @@ -71,8 +71,8 @@ typedef int * Functions of this type are called by libbrandt to report the auction outcome * or malicious/erroneous participants. * - * TODO: update price type. - * TODO: export proof of erroneous behaviour. + * \todo: update price type. + * \todo: export proof of erroneous behaviour. * * @param[in] auction_closure Closure pointer representing the respective * auction. This is the Pointer given to BRANDT_join() / BRANDT_new(). @@ -115,16 +115,16 @@ BRANDT_join (BRANDT_BroadcastCallback broadcast, const void * auction_closure, const void * auction_data, size_t auction_data_len); -/* FIXME: where do I specify my bid? */ +/* \todo: where do I specify my bid? */ -/* FIXME: Distinguish handles for seller/buyers */ -/* FIXME: have cancellation (BRANDT_join_cancel()) */ -/* FIXME: provide means to extract a hash from auction data to */ +/* \todo: Distinguish handles for seller/buyers */ +/* \todo: have cancellation (BRANDT_join_cancel()) */ +/* \todo: provide means to extract a hash from auction data to */ /* tie cryptographic operations to application-readable proposal */ -/* FIXME: have separate function to export 'out' variables */ -/* FIXME: might want to specify timeout? How do we deal with time? */ -/* FIXME: separate creating an auction from starting it; initial */ +/* \todo: have separate function to export 'out' variables */ +/* \todo: might want to specify timeout? How do we deal with time? */ +/* \todo: separate creating an auction from starting it; initial */ /* setup needs more auction proposal details (hash, timeout, */ /* bid structure), later we need to know # participants */ /** @@ -140,15 +140,15 @@ BRANDT_join (BRANDT_BroadcastCallback broadcast, * @param[out] auction_data_len The length in bytes of the @a auction_data * structure. Will be filled by BRANDT_new(). * @param[in] num_prices The amount of possible valuations for the sold item(s). - * If 0, a default of 256 will be used. TODO: what about 1, does it work with + * If 0, a default of 256 will be used. \todo: what about 1, does it work with * second price auctions? * @param[in] m The mode of the auction. If 0, it will be a first price auction * where the winner has to pay the price of his bid. If >0 it will be a second * price auction selling exactly that amount of items and each winner has to pay - * the price of the highest loosing bid. TODO: what if bidders < m? + * the price of the highest loosing bid. \todo: what if bidders < m? * @param[in] outcome_public If 1, the auction winner and price will be public * to all participants, if 0, this information will only be revealed to the - * winner and the seller. => FIXME: Turn into AuctionMode bit flag! + * winner and the seller. => \todo: Turn into AuctionMode bit flag! * @return A pointer, which should only be remembered and passed to * libbrandt functions when the client needs to refer to this auction. This is a * black-box pointer, do NOT access/change it or the data it points to! @@ -185,7 +185,7 @@ BRANDT_got_broadcast (struct BRANDT_Auction *auction, * @a msg was received. * @param[in] msg The message that was received. * @param[in] msg_len The length in bytes of @a msg. - * TODO: how to link message to sender id within auction? + * \todo: how to link message to sender id within auction? * ANSWER: on start, know that we have 'n' participants, here give * participant number (1..n) */ @@ -195,6 +195,6 @@ BRANDT_got_unicast (struct BRANDT_Auction *auction, size_t msg_len); -/**TODO: Error handling functions? */ +/**\todo: Error handling functions? */ #endif /* ifndef _BRANDT_BRANDT_H */ diff --git a/crypto.c b/crypto.c index 0c2597d..044db00 100644 --- a/crypto.c +++ b/crypto.c @@ -324,7 +324,7 @@ smc_free2 (gcry_mpi_point_t **dst, uint16_t size1, uint16_t size2) /** * smc_sums_partial calculates sums up until the current index and stores them - * in @a out. @$f\forall i \leq len: out_i=sum_{h=1}^iin_h@$f + * in @a out. \f$\forall i \leq len: out_i=\sum_{h=1}^iin_h\f$ * * @param[out] out Where to store the resulting sums. Points may be given * uninitialized, but the appropriate amount of memory has to be allocated @@ -347,7 +347,8 @@ smc_sums_partial (gcry_mpi_point_t out[], gcry_mpi_point_t in[], uint16_t len) /** - * smc_sum calculates the sum of all input points. @$fout=sum_{i=1}^{len}in_i@$f + * smc_sum calculates the sum of all input points. + * \f$out=\sum_{i=1}^{len}in_i\f$ * * @param[out] out Where to store the result * @param[in] in Input points. @@ -359,7 +360,7 @@ smc_sum (gcry_mpi_point_t out, gcry_mpi_point_t in[], uint16_t len) uint16_t i; brandt_assert (NULL != out); - /**TODO: how to copy a point more efficiently? */ + /**\todo: how to copy a point more efficiently? */ gcry_mpi_ec_add (out, ec_zero, ec_zero, ec_ctx); for (i = 0; i < len; i++) gcry_mpi_ec_add (out, out, in[i], ec_ctx); @@ -382,12 +383,12 @@ smc_compute_pkey (struct AuctionData *ad) /** * smc_zkp_dl * - * @param v TODO - * @param g TODO - * @param x TODO - * @param a TODO - * @param c TODO - * @param r TODO + * @param v \todo + * @param g \todo + * @param x \todo + * @param a \todo + * @param c \todo + * @param r \todo */ void smc_zkp_dl (const gcry_mpi_point_t v, @@ -402,7 +403,7 @@ smc_zkp_dl (const gcry_mpi_point_t v, ec_keypair_create_base (a, z, g); /* compute challange c */ - /**TODO: generate c from HASH(g,v,a) and don't output it */ + /**\todo: generate c from HASH(g,v,a) and don't output it */ ec_skey_create (c); gcry_mpi_mod (c, c, ec_n); @@ -416,11 +417,11 @@ smc_zkp_dl (const gcry_mpi_point_t v, /** * smc_zkp_dl_check * - * @param v TODO - * @param g TODO - * @param a TODO - * @param c TODO - * @param r TODO + * @param v \todo + * @param g \todo + * @param a \todo + * @param c \todo + * @param r \todo * @return 0 if the proof is correct, something else otherwise */ int @@ -463,7 +464,7 @@ smc_zkp_2dle (const gcry_mpi_point_t v, gcry_mpi_ec_mul (b, z, g2, ec_ctx); /* compute challange c */ - /**TODO: generate c from HASH(g1,g2,v,w,a,b) and don't output it */ + /* \todo: generate c from HASH(g1,g2,v,w,a,b) and don't output it */ ec_skey_create (c); gcry_mpi_mod (c, c, ec_n); @@ -560,7 +561,7 @@ smc_zkp_0og (gcry_mpi_point_t alpha, gcry_mpi_ec_mul (b2, w, y, ec_ctx); /* compute challange c */ - /**TODO: generate c from HASH(alpha,beta,a1,b1,a2,b2) and don't output it */ + /* \todo: generate c from HASH(alpha,beta,a1,b1,a2,b2) and don't output it */ ec_skey_create (c); gcry_mpi_mod (c, c, ec_n); @@ -596,7 +597,7 @@ smc_zkp_0og (gcry_mpi_point_t alpha, gcry_mpi_ec_mul (b1, w, y, ec_ctx); /* compute challange c */ - /**TODO: generate c from HASH(alpha,beta,a1,b1,a2,b2) and don't output it */ + /* \todo: generate c from HASH(alpha,beta,a1,b1,a2,b2) and don't output it */ ec_skey_create (c); gcry_mpi_mod (c, c, ec_n); diff --git a/doc/Makefile.am b/doc/Makefile.am index 9a68059..5e09f24 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -11,4 +11,4 @@ fast: brandt.doxy sed 's/\(HAVE_DOT.*=\).*/\1 NO/' $< | doxygen - clean: - rm -rf html + rm -rf html man diff --git a/doc/brandt.doxy b/doc/brandt.doxy index 944d13b..76b1538 100644 --- a/doc/brandt.doxy +++ b/doc/brandt.doxy @@ -44,7 +44,7 @@ PROJECT_NUMBER = # for a project that appears at the top of each page and should give viewer a # quick idea about the purpose of the project. Keep the description short. -PROJECT_BRIEF = "confidential and deniable group chats" +PROJECT_BRIEF = "fully private and secure auctions" # With the PROJECT_LOGO tag one can specify a logo or an icon that is included # in the documentation. The maximum height of the logo should not exceed 55 diff --git a/test_crypto.c b/test_crypto.c index a42a643..6d4a029 100644 --- a/test_crypto.c +++ b/test_crypto.c @@ -60,7 +60,7 @@ test_smc_zkp_dl () if (0 == tests_run) { - /**TODO: there has to be a better way to copy a point */ + /* \todo: there has to be a better way to copy a point */ gcry_mpi_ec_mul (g, GCRYMPI_CONST_ONE, ec_gen, ec_ctx); } @@ -100,7 +100,7 @@ test_smc_zkp_2dle () if (0 == tests_run) { - /**TODO: there has to be a better way to copy a point */ + /* \todo: there has to be a better way to copy a point */ gcry_mpi_ec_mul (g1, GCRYMPI_CONST_ONE, ec_gen, ec_ctx); gcry_mpi_ec_mul (g2, GCRYMPI_CONST_ONE, ec_gen, ec_ctx); } diff --git a/uncrustify/file_header b/uncrustify/file_header index a490afe..04db3a9 100644 --- a/uncrustify/file_header +++ b/uncrustify/file_header @@ -16,5 +16,5 @@ /** * @file $(filename) - * @brief TODO + * @brief \todo */ diff --git a/util.c b/util.c index 2acd726..5eebd3c 100644 --- a/util.c +++ b/util.c @@ -16,7 +16,7 @@ /** * @file util.c - * @brief TODO + * @brief \todo */ #include #include @@ -25,52 +25,19 @@ #include "util.h" -static void xvprintf (const char *, va_list); /** - * eprintf + * xvprintf prints a formatstring with prefix "libbrandt: ". If the format + * string ends with a ':', the strerror() from errno.h output will be appended. + * The output is always terminated with a newline. * - * @param fmt TODO - * @param - */ -void -eprintf (const char *fmt, ...) -{ - va_list ap; - - va_start (ap, fmt); - xvprintf (fmt, ap); - va_end (ap); - - abort (); -} - -/** - * weprintf - * - * @param fmt TODO - * @param - */ -void -weprintf (const char *fmt, ...) -{ - va_list ap; - - va_start (ap, fmt); - xvprintf (fmt, ap); - va_end (ap); -} - -/** - * xvprintf - * - * @param fmt TODO - * @param ap TODO + * @param fmt The format string + * @param ap The inputs to the format string */ void xvprintf (const char *fmt, va_list ap) { - /**TODO: provide other logging target than stderr */ + /**\todo: provide other logging target than stderr */ fputs ("libbrandt: ", stderr); vfprintf (stderr, fmt, ap); @@ -85,3 +52,40 @@ xvprintf (const char *fmt, va_list ap) fputc ('\n', stderr); } } + + +/** + * eprintf prints an error message and then calls abort() to terminate the + * process. + * + * @param fmt The format string + * @param ... The inputs to the format string + */ +void +eprintf (const char *fmt, ...) +{ + va_list ap; + + va_start (ap, fmt); + xvprintf (fmt, ap); + va_end (ap); + + abort (); +} + + +/** + * weprintf prints a warning message + * + * @param fmt The format string + * @param ... The inputs to the format string + */ +void +weprintf (const char *fmt, ...) +{ + va_list ap; + + va_start (ap, fmt); + xvprintf (fmt, ap); + va_end (ap); +}