shared_random.[ch]: repair doxygen comments

1 files changed, 30 insertions, 29 deletions

diff --git a/src/feature/dirauth/shared_random.h b/src/feature/dirauth/shared_random.h
index 7ff9f15512..b3b4b3a2aa 100644
--- a/src/feature/dirauth/shared_random.h
+++ b/src/feature/dirauth/shared_random.h
@@ -4,83 +4,85 @@
 #ifndef TOR_SHARED_RANDOM_H
 #define TOR_SHARED_RANDOM_H
 
-/*
- * This file contains ABI/API of the shared random protocol defined in
+/**
+ * \file shared_random.h
+ *
+ * \brief This file contains ABI/API of the shared random protocol defined in
  * proposal #250. Every public functions and data structure are namespaced
  * with "sr_" which stands for shared random.
  */
 
 #include "core/or/or.h"
 
-/* Protocol version */
+/** Protocol version */
 #define SR_PROTO_VERSION  1
-/* Default digest algorithm. */
+/** Default digest algorithm. */
 #define SR_DIGEST_ALG DIGEST_SHA3_256
-/* Invariant token in the SRV calculation. */
+/** Invariant token in the SRV calculation. */
 #define SR_SRV_TOKEN "shared-random"
-/* Don't count the NUL terminated byte even though the TOKEN has it. */
+/** Don't count the NUL terminated byte even though the TOKEN has it. */
 #define SR_SRV_TOKEN_LEN (sizeof(SR_SRV_TOKEN) - 1)
 
-/* Length of the random number (in bytes). */
+/** Length of the random number (in bytes). */
 #define SR_RANDOM_NUMBER_LEN 32
-/* Size of a decoded commit value in a vote or state. It's a hash and a
+/** Size of a decoded commit value in a vote or state. It's a hash and a
  * timestamp. It adds up to 40 bytes. */
 #define SR_COMMIT_LEN (sizeof(uint64_t) + DIGEST256_LEN)
-/* Size of a decoded reveal value from a vote or state. It's a 64 bit
+/** Size of a decoded reveal value from a vote or state. It's a 64 bit
  * timestamp and the hashed random number. This adds up to 40 bytes. */
 #define SR_REVEAL_LEN (sizeof(uint64_t) + DIGEST256_LEN)
-/* Size of SRV message length. The construction is has follow:
+/** Size of SRV message length. The construction is has follow:
  *  "shared-random" | INT_8(reveal_num) | INT_4(version) | PREV_SRV */
 #define SR_SRV_MSG_LEN \
   (SR_SRV_TOKEN_LEN + sizeof(uint64_t) + sizeof(uint32_t) + DIGEST256_LEN)
 
-/* Length of base64 encoded commit NOT including the NUL terminated byte.
+/** Length of base64 encoded commit NOT including the NUL terminated byte.
  * Formula is taken from base64_encode_size. This adds up to 56 bytes. */
 #define SR_COMMIT_BASE64_LEN (BASE64_LEN(SR_COMMIT_LEN))
-/* Length of base64 encoded reveal NOT including the NUL terminated byte.
+/** Length of base64 encoded reveal NOT including the NUL terminated byte.
  * Formula is taken from base64_encode_size. This adds up to 56 bytes. */
 #define SR_REVEAL_BASE64_LEN (BASE64_LEN(SR_REVEAL_LEN))
-/* Length of base64 encoded shared random value. It's 32 bytes long so 44
+/** Length of base64 encoded shared random value. It's 32 bytes long so 44
  * bytes from the base64_encode_size formula. That includes the '='
  * character at the end. */
 #define SR_SRV_VALUE_BASE64_LEN (BASE64_LEN(DIGEST256_LEN))
 
-/* Assert if commit valid flag is not set. */
+/** Assert if commit valid flag is not set. */
 #define ASSERT_COMMIT_VALID(c) tor_assert((c)->valid)
 
-/* Protocol phase. */
+/** Protocol phase. */
 typedef enum {
-  /* Commitment phase */
+  /** Commitment phase */
   SR_PHASE_COMMIT  = 1,
-  /* Reveal phase */
+  /** Reveal phase */
   SR_PHASE_REVEAL  = 2,
 } sr_phase_t;
 
-/* A shared random value (SRV). */
+/** A shared random value (SRV). */
 typedef struct sr_srv_t {
-  /* The number of reveal values used to derive this SRV. */
+  /** The number of reveal values used to derive this SRV. */
   uint64_t num_reveals;
-  /* The actual value. This is the stored result of SHA3-256. */
+  /** The actual value. This is the stored result of SHA3-256. */
   uint8_t value[DIGEST256_LEN];
 } sr_srv_t;
 
-/* A commit (either ours or from another authority). */
+/** A commit (either ours or from another authority). */
 typedef struct sr_commit_t {
-  /* Hashing algorithm used. */
+  /** Hashing algorithm used. */
   digest_algorithm_t alg;
-  /* Indicate if this commit has been verified thus valid. */
+  /** Indicate if this commit has been verified thus valid. */
   unsigned int valid:1;
 
   /* Commit owner info */
 
-  /* The RSA identity key of the authority and its base16 representation,
+  /** The RSA identity key of the authority and its base16 representation,
    * which includes the NUL terminated byte. */
   char rsa_identity[DIGEST_LEN];
   char rsa_identity_hex[HEX_DIGEST_LEN + 1];
 
   /* Commitment information */
 
-  /* Timestamp of reveal. Correspond to TIMESTAMP. */
+  /** Timestamp of reveal. Correspond to TIMESTAMP. */
   uint64_t reveal_ts;
   /* H(REVEAL) as found in COMMIT message. */
   char hashed_reveal[DIGEST256_LEN];
@@ -89,13 +91,13 @@ typedef struct sr_commit_t {
 
   /* Reveal information */
 
-  /* H(RN) which is what we used as the random value for this commit. We
+  /** H(RN) which is what we used as the random value for this commit. We
    * don't use the raw bytes since those are sent on the network thus
    * avoiding possible information leaks of our PRNG. */
   uint8_t random_number[SR_RANDOM_NUMBER_LEN];
-  /* Timestamp of commit. Correspond to TIMESTAMP. */
+  /** Timestamp of commit. Correspond to TIMESTAMP. */
   uint64_t commit_ts;
-  /* This is the whole reveal message. We use it during verification */
+  /** This is the whole reveal message. We use it during verification */
   char encoded_reveal[SR_REVEAL_BASE64_LEN + 1];
 } sr_commit_t;
 
@@ -191,4 +193,3 @@ void set_num_srv_agreements(int32_t value);
 #endif /* TOR_UNIT_TESTS */
 
 #endif /* !defined(TOR_SHARED_RANDOM_H) */
-