[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[tor-commits] [tor/master] Fix various doxygen comments in feature/hs.



commit 582cee723a86e44f140a5057152df06659c36e71
Author: Nick Mathewson <nickm@xxxxxxxxxxxxxx>
Date:   Thu Nov 7 08:13:31 2019 -0500

    Fix various doxygen comments in feature/hs.
---
 src/feature/hs/hs_circuit.c                  | 54 ++++++++++++------------
 src/feature/hs/hs_circuitmap.c               | 63 ++++++++++++++--------------
 src/feature/hs/hs_common.c                   |  8 ++--
 src/feature/hs/hs_config.c                   | 22 +++++-----
 src/feature/hs/hs_control.c                  | 18 ++++----
 src/feature/hs/hs_dos.c                      | 26 ++++++------
 src/feature/hs/hs_intropoint.c               | 30 ++++++-------
 src/feature/hs/hs_intropoint.h               |  9 ++--
 src/feature/hs/hs_service.c                  |  8 ++--
 src/feature/hs/hs_service.h                  |  6 +++
 src/feature/hs/hsdir_index_st.h              |  7 ++--
 src/feature/hs_common/replaycache.h          | 13 ++++--
 src/feature/hs_common/shared_random_client.c | 19 ++++-----
 13 files changed, 147 insertions(+), 136 deletions(-)

diff --git a/src/feature/hs/hs_circuit.c b/src/feature/hs/hs_circuit.c
index e1e9c7c79..9d21acf42 100644
--- a/src/feature/hs/hs_circuit.c
+++ b/src/feature/hs/hs_circuit.c
@@ -40,7 +40,7 @@
 #include "feature/nodelist/node_st.h"
 #include "core/or/origin_circuit_st.h"
 
-/* A circuit is about to become an e2e rendezvous circuit. Check
+/** A circuit is about to become an e2e rendezvous circuit. Check
  * <b>circ_purpose</b> and ensure that it's properly set. Return true iff
  * circuit purpose is properly set, otherwise return false. */
 static int
@@ -67,7 +67,7 @@ circuit_purpose_is_correct_for_rend(unsigned int circ_purpose,
   return 1;
 }
 
-/* Create and return a crypt path for the final hop of a v3 prop224 rendezvous
+/** Create and return a crypt path for the final hop of a v3 prop224 rendezvous
  * circuit. Initialize the crypt path crypto using the output material from the
  * ntor key exchange at <b>ntor_key_seed</b>.
  *
@@ -101,7 +101,7 @@ create_rend_cpath(const uint8_t *ntor_key_seed, size_t seed_len,
   return cpath;
 }
 
-/* We are a v2 legacy HS client: Create and return a crypt path for the hidden
+/** We are a v2 legacy HS client: Create and return a crypt path for the hidden
  * service on the other side of the rendezvous circuit <b>circ</b>. Initialize
  * the crypt path crypto using the body of the RENDEZVOUS1 cell at
  * <b>rend_cell_body</b> (which must be at least DH1024_KEY_LEN+DIGEST_LEN
@@ -152,7 +152,7 @@ create_rend_cpath_legacy(origin_circuit_t *circ, const uint8_t *rend_cell_body)
   return hop;
 }
 
-/* Append the final <b>hop</b> to the cpath of the rend <b>circ</b>, and mark
+/** Append the final <b>hop</b> to the cpath of the rend <b>circ</b>, and mark
  * <b>circ</b> ready for use to transfer HS relay cells. */
 static void
 finalize_rend_circuit(origin_circuit_t *circ, crypt_path_t *hop,
@@ -193,7 +193,7 @@ finalize_rend_circuit(origin_circuit_t *circ, crypt_path_t *hop,
   }
 }
 
-/* For a given circuit and a service introduction point object, register the
+/** For a given circuit and a service introduction point object, register the
  * intro circuit to the circuitmap. This supports legacy intro point. */
 static void
 register_intro_circ(const hs_service_intro_point_t *ip,
@@ -211,7 +211,7 @@ register_intro_circ(const hs_service_intro_point_t *ip,
   }
 }
 
-/* Return the number of opened introduction circuit for the given circuit that
+/** Return the number of opened introduction circuit for the given circuit that
  * is matching its identity key. */
 static unsigned int
 count_opened_desc_intro_point_circuits(const hs_service_t *service,
@@ -243,7 +243,7 @@ count_opened_desc_intro_point_circuits(const hs_service_t *service,
   return count;
 }
 
-/* From a given service, rendezvous cookie and handshake info, create a
+/** From a given service, rendezvous cookie and handshake info, create a
  * rendezvous point circuit identifier. This can't fail. */
 STATIC hs_ident_circuit_t *
 create_rp_circuit_identifier(const hs_service_t *service,
@@ -282,7 +282,7 @@ create_rp_circuit_identifier(const hs_service_t *service,
   return ident;
 }
 
-/* From a given service and service intro point, create an introduction point
+/** From a given service and service intro point, create an introduction point
  * circuit identifier. This can't fail. */
 static hs_ident_circuit_t *
 create_intro_circuit_identifier(const hs_service_t *service,
@@ -299,7 +299,7 @@ create_intro_circuit_identifier(const hs_service_t *service,
   return ident;
 }
 
-/* For a given introduction point and an introduction circuit, send the
+/** For a given introduction point and an introduction circuit, send the
  * ESTABLISH_INTRO cell. The service object is used for logging. This can fail
  * and if so, the circuit is closed and the intro point object is flagged
  * that the circuit is not established anymore which is important for the
@@ -349,7 +349,7 @@ send_establish_intro(const hs_service_t *service,
   memwipe(payload, 0, sizeof(payload));
 }
 
-/* Return a string constant describing the anonymity of service. */
+/** Return a string constant describing the anonymity of service. */
 static const char *
 get_service_anonymity_string(const hs_service_t *service)
 {
@@ -360,7 +360,7 @@ get_service_anonymity_string(const hs_service_t *service)
   }
 }
 
-/* For a given service, the ntor onion key and a rendezvous cookie, launch a
+/** For a given service, the ntor onion key and a rendezvous cookie, launch a
  * circuit to the rendezvous point specified by the link specifiers. On
  * success, a circuit identifier is attached to the circuit with the needed
  * data. This function will try to open a circuit for a maximum value of
@@ -469,7 +469,7 @@ launch_rendezvous_point_circuit(const hs_service_t *service,
   extend_info_free(info);
 }
 
-/* Return true iff the given service rendezvous circuit circ is allowed for a
+/** Return true iff the given service rendezvous circuit circ is allowed for a
  * relaunch to the rendezvous point. */
 static int
 can_relaunch_service_rendezvous_point(const origin_circuit_t *circ)
@@ -516,7 +516,7 @@ can_relaunch_service_rendezvous_point(const origin_circuit_t *circ)
   return 0;
 }
 
-/* Retry the rendezvous point of circ by launching a new circuit to it. */
+/** Retry the rendezvous point of circ by launching a new circuit to it. */
 static void
 retry_service_rendezvous_point(const origin_circuit_t *circ)
 {
@@ -565,7 +565,7 @@ retry_service_rendezvous_point(const origin_circuit_t *circ)
   return;
 }
 
-/* Using the given descriptor intro point ip, the node of the
+/** Using the given descriptor intro point ip, the node of the
  * rendezvous point rp_node and the service's subcredential, populate the
  * already allocated intro1_data object with the needed key material and link
  * specifiers.
@@ -622,7 +622,7 @@ setup_introduce1_data(const hs_desc_intro_point_t *ip,
 /* Public API */
 /* ========== */
 
-/* Return an introduction point circuit matching the given intro point object.
+/** Return an introduction point circuit matching the given intro point object.
  * NULL is returned is no such circuit can be found. */
 origin_circuit_t *
 hs_circ_service_get_intro_circ(const hs_service_intro_point_t *ip)
@@ -637,7 +637,7 @@ hs_circ_service_get_intro_circ(const hs_service_intro_point_t *ip)
   }
 }
 
-/* Return an introduction point established circuit matching the given intro
+/** Return an introduction point established circuit matching the given intro
  * point object. The circuit purpose has to be CIRCUIT_PURPOSE_S_INTRO. NULL
  * is returned is no such circuit can be found. */
 origin_circuit_t *
@@ -658,7 +658,7 @@ hs_circ_service_get_established_intro_circ(const hs_service_intro_point_t *ip)
   return (TO_CIRCUIT(circ)->purpose == CIRCUIT_PURPOSE_S_INTRO) ? circ : NULL;
 }
 
-/* Called when we fail building a rendezvous circuit at some point other than
+/** Called when we fail building a rendezvous circuit at some point other than
  * the last hop: launches a new circuit to the same rendezvous point. This
  * supports legacy service.
  *
@@ -698,7 +698,7 @@ hs_circ_retry_service_rendezvous_point(origin_circuit_t *circ)
   return;
 }
 
-/* For a given service and a service intro point, launch a circuit to the
+/** For a given service and a service intro point, launch a circuit to the
  * extend info ei. If the service is a single onion, and direct_conn is true,
  * a one-hop circuit will be requested.
  *
@@ -759,7 +759,7 @@ hs_circ_launch_intro_point(hs_service_t *service,
   return ret;
 }
 
-/* Called when a service introduction point circuit is done building. Given
+/** Called when a service introduction point circuit is done building. Given
  * the service and intro point object, this function will send the
  * ESTABLISH_INTRO cell on the circuit. Return 0 on success. Return 1 if the
  * circuit has been repurposed to General because we already have too many
@@ -828,7 +828,7 @@ hs_circ_service_intro_has_opened(hs_service_t *service,
   return ret;
 }
 
-/* Called when a service rendezvous point circuit is done building. Given the
+/** Called when a service rendezvous point circuit is done building. Given the
  * service and the circuit, this function will send a RENDEZVOUS1 cell on the
  * circuit using the information in the circuit identifier. If the cell can't
  * be sent, the circuit is closed. */
@@ -894,7 +894,7 @@ hs_circ_service_rp_has_opened(const hs_service_t *service,
   memwipe(payload, 0, sizeof(payload));
 }
 
-/* Circ has been expecting an INTRO_ESTABLISHED cell that just arrived. Handle
+/** Circ has been expecting an INTRO_ESTABLISHED cell that just arrived. Handle
  * the INTRO_ESTABLISHED cell payload of length payload_len arriving on the
  * given introduction circuit circ. The service is only used for logging
  * purposes. Return 0 on success else a negative value. */
@@ -939,7 +939,7 @@ hs_circ_handle_intro_established(const hs_service_t *service,
   return ret;
 }
 
-/* We just received an INTRODUCE2 cell on the established introduction circuit
+/** We just received an INTRODUCE2 cell on the established introduction circuit
  * circ.  Handle the INTRODUCE2 payload of size payload_len for the given
  * circuit and service. This cell is associated with the intro point object ip
  * and the subcredential. Return 0 on success else a negative value. */
@@ -1006,7 +1006,7 @@ hs_circ_handle_introduce2(const hs_service_t *service,
   return ret;
 }
 
-/* Circuit <b>circ</b> just finished the rend ntor key exchange. Use the key
+/** Circuit <b>circ</b> just finished the rend ntor key exchange. Use the key
  * exchange output material at <b>ntor_key_seed</b> and setup <b>circ</b> to
  * serve as a rendezvous end-to-end circuit between the client and the
  * service. If <b>is_service_side</b> is set, then we are the hidden service
@@ -1036,7 +1036,7 @@ hs_circuit_setup_e2e_rend_circ(origin_circuit_t *circ,
   return 0;
 }
 
-/* We are a v2 legacy HS client and we just received a RENDEZVOUS1 cell
+/** We are a v2 legacy HS client and we just received a RENDEZVOUS1 cell
  * <b>rend_cell_body</b> on <b>circ</b>. Finish up the DH key exchange and then
  * extend the crypt path of <b>circ</b> so that the hidden service is on the
  * other side. */
@@ -1061,7 +1061,7 @@ hs_circuit_setup_e2e_rend_circ_legacy_client(origin_circuit_t *circ,
   return 0;
 }
 
-/* Given the introduction circuit intro_circ, the rendezvous circuit
+/** Given the introduction circuit intro_circ, the rendezvous circuit
  * rend_circ, a descriptor intro point object ip and the service's
  * subcredential, send an INTRODUCE1 cell on intro_circ.
  *
@@ -1146,7 +1146,7 @@ hs_circ_send_introduce1(origin_circuit_t *intro_circ,
   return ret;
 }
 
-/* Send an ESTABLISH_RENDEZVOUS cell along the rendezvous circuit circ. On
+/** Send an ESTABLISH_RENDEZVOUS cell along the rendezvous circuit circ. On
  * success, 0 is returned else -1 and the circuit is marked for close. */
 int
 hs_circ_send_establish_rendezvous(origin_circuit_t *circ)
@@ -1197,7 +1197,7 @@ hs_circ_send_establish_rendezvous(origin_circuit_t *circ)
   return -1;
 }
 
-/* We are about to close or free this <b>circ</b>. Clean it up from any
+/** We are about to close or free this <b>circ</b>. Clean it up from any
  * related HS data structures. This function can be called multiple times
  * safely for the same circuit. */
 void
diff --git a/src/feature/hs/hs_circuitmap.c b/src/feature/hs/hs_circuitmap.c
index e34f564fb..0df451948 100644
--- a/src/feature/hs/hs_circuitmap.c
+++ b/src/feature/hs/hs_circuitmap.c
@@ -23,13 +23,13 @@
 
 /************************** HS circuitmap code *******************************/
 
-/* This is the hidden service circuitmap. It's a hash table that maps
+/** This is the hidden service circuitmap. It's a hash table that maps
    introduction and rendezvous tokens to specific circuits such that given a
    token it's easy to find the corresponding circuit. */
 static struct hs_circuitmap_ht *the_hs_circuitmap = NULL;
 
-/* This is a helper function used by the hash table code (HT_). It returns 1 if
- * two circuits have the same HS token. */
+/** This is a helper function used by the hash table code (HT_). It returns 1
+ * if two circuits have the same HS token. */
 static int
 hs_circuits_have_same_token(const circuit_t *first_circuit,
                             const circuit_t *second_circuit)
@@ -60,8 +60,9 @@ hs_circuits_have_same_token(const circuit_t *first_circuit,
                    first_token->token_len);
 }
 
-/* This is a helper function for the hash table code (HT_). It hashes a circuit
- * HS token into an unsigned int for use as a key by the hash table routines.*/
+/** This is a helper function for the hash table code (HT_). It hashes a
+ * circuit HS token into an unsigned int for use as a key by the hash table
+ * routines.*/
 static inline unsigned int
 hs_circuit_hash_token(const circuit_t *circuit)
 {
@@ -71,7 +72,7 @@ hs_circuit_hash_token(const circuit_t *circuit)
                                circuit->hs_token->token_len);
 }
 
-/* Register the circuitmap hash table */
+/** Register the circuitmap hash table */
 HT_PROTOTYPE(hs_circuitmap_ht, // The name of the hashtable struct
              circuit_t,    // The name of the element struct,
              hs_circuitmap_node,        // The name of HT_ENTRY member
@@ -83,7 +84,7 @@ HT_GENERATE2(hs_circuitmap_ht, circuit_t, hs_circuitmap_node,
 
 #ifdef TOR_UNIT_TESTS
 
-/* Return the global HS circuitmap. Used by unittests. */
+/** Return the global HS circuitmap. Used by unittests. */
 hs_circuitmap_ht *
 get_hs_circuitmap(void)
 {
@@ -136,7 +137,7 @@ get_circuit_with_token(hs_token_t *search_token)
   return HT_FIND(hs_circuitmap_ht, the_hs_circuitmap, &search_circ);
 }
 
-/* Helper function that registers <b>circ</b> with <b>token</b> on the HS
+/** Helper function that registers <b>circ</b> with <b>token</b> on the HS
    circuitmap. This function steals reference of <b>token</b>. */
 static void
 hs_circuitmap_register_impl(circuit_t *circ, hs_token_t *token)
@@ -186,7 +187,7 @@ hs_circuitmap_register_circuit(circuit_t *circ,
   hs_circuitmap_register_impl(circ, hs_token);
 }
 
-/* Helper function for hs_circuitmap_get_origin_circuit() and
+/** Helper function for hs_circuitmap_get_origin_circuit() and
  * hs_circuitmap_get_or_circuit(). Because only circuit_t are indexed in the
  * circuitmap, this function returns object type so the specialized functions
  * using this helper can upcast it to the right type.
@@ -220,7 +221,7 @@ hs_circuitmap_get_circuit_impl(hs_token_type_t type,
   return found_circ;
 }
 
-/* Helper function: Query circuitmap for origin circuit with <b>token</b> of
+/** Helper function: Query circuitmap for origin circuit with <b>token</b> of
  * size <b>token_len</b> and <b>type</b>.  Only returns a circuit with purpose
  * equal to the <b>wanted_circ_purpose</b> parameter and if it is NOT marked
  * for close. Return NULL if no such circuit is found. */
@@ -244,7 +245,7 @@ hs_circuitmap_get_origin_circuit(hs_token_type_t type,
   return TO_ORIGIN_CIRCUIT(circ);
 }
 
-/* Helper function: Query circuitmap for OR circuit with <b>token</b> of size
+/** Helper function: Query circuitmap for OR circuit with <b>token</b> of size
  * <b>token_len</b> and <b>type</b>.  Only returns a circuit with purpose equal
  * to the <b>wanted_circ_purpose</b> parameter and if it is NOT marked for
  * close. Return NULL if no such circuit is found. */
@@ -272,7 +273,7 @@ hs_circuitmap_get_or_circuit(hs_token_type_t type,
 
 /**** Public relay-side getters: */
 
-/* Public function: Return v2 and v3 introduction circuit to this relay.
+/** Public function: Return v2 and v3 introduction circuit to this relay.
  * Always return a newly allocated list for which it is the caller's
  * responsability to free it. */
 smartlist_t *
@@ -299,7 +300,7 @@ hs_circuitmap_get_all_intro_circ_relay_side(void)
   return circuit_list;
 }
 
-/* Public function: Return a v3 introduction circuit to this relay with
+/** Public function: Return a v3 introduction circuit to this relay with
  * <b>auth_key</b>. Return NULL if no such circuit is found in the
  * circuitmap. */
 or_circuit_t *
@@ -311,7 +312,7 @@ hs_circuitmap_get_intro_circ_v3_relay_side(
                                       CIRCUIT_PURPOSE_INTRO_POINT);
 }
 
-/* Public function: Return v2 introduction circuit to this relay with
+/** Public function: Return v2 introduction circuit to this relay with
  * <b>digest</b>. Return NULL if no such circuit is found in the circuitmap. */
 or_circuit_t *
 hs_circuitmap_get_intro_circ_v2_relay_side(const uint8_t *digest)
@@ -321,7 +322,7 @@ hs_circuitmap_get_intro_circ_v2_relay_side(const uint8_t *digest)
                                       CIRCUIT_PURPOSE_INTRO_POINT);
 }
 
-/* Public function: Return rendezvous circuit to this relay with rendezvous
+/** Public function: Return rendezvous circuit to this relay with rendezvous
  * <b>cookie</b>. Return NULL if no such circuit is found in the circuitmap. */
 or_circuit_t *
 hs_circuitmap_get_rend_circ_relay_side(const uint8_t *cookie)
@@ -333,7 +334,7 @@ hs_circuitmap_get_rend_circ_relay_side(const uint8_t *cookie)
 
 /** Public relay-side setters: */
 
-/* Public function: Register rendezvous circuit with key <b>cookie</b> to the
+/** Public function: Register rendezvous circuit with key <b>cookie</b> to the
  * circuitmap. */
 void
 hs_circuitmap_register_rend_circ_relay_side(or_circuit_t *circ,
@@ -343,7 +344,7 @@ hs_circuitmap_register_rend_circ_relay_side(or_circuit_t *circ,
                                  HS_TOKEN_REND_RELAY_SIDE,
                                  REND_TOKEN_LEN, cookie);
 }
-/* Public function: Register v2 intro circuit with key <b>digest</b> to the
+/** Public function: Register v2 intro circuit with key <b>digest</b> to the
  * circuitmap. */
 void
 hs_circuitmap_register_intro_circ_v2_relay_side(or_circuit_t *circ,
@@ -354,7 +355,7 @@ hs_circuitmap_register_intro_circ_v2_relay_side(or_circuit_t *circ,
                                  REND_TOKEN_LEN, digest);
 }
 
-/* Public function: Register v3 intro circuit with key <b>auth_key</b> to the
+/** Public function: Register v3 intro circuit with key <b>auth_key</b> to the
  * circuitmap. */
 void
 hs_circuitmap_register_intro_circ_v3_relay_side(or_circuit_t *circ,
@@ -367,7 +368,7 @@ hs_circuitmap_register_intro_circ_v3_relay_side(or_circuit_t *circ,
 
 /**** Public servide-side getters: */
 
-/* Public function: Return v3 introduction circuit with <b>auth_key</b>
+/** Public function: Return v3 introduction circuit with <b>auth_key</b>
  * originating from this hidden service. Return NULL if no such circuit is
  * found in the circuitmap. */
 origin_circuit_t *
@@ -392,9 +393,9 @@ hs_circuitmap_get_intro_circ_v3_service_side(const
   return circ;
 }
 
-/* Public function: Return v2 introduction circuit originating from this hidden
- * service with <b>digest</b>. Return NULL if no such circuit is found in the
- * circuitmap. */
+/** Public function: Return v2 introduction circuit originating from this
+ * hidden service with <b>digest</b>. Return NULL if no such circuit is found
+ * in the circuitmap. */
 origin_circuit_t *
 hs_circuitmap_get_intro_circ_v2_service_side(const uint8_t *digest)
 {
@@ -416,7 +417,7 @@ hs_circuitmap_get_intro_circ_v2_service_side(const uint8_t *digest)
   return circ;
 }
 
-/* Public function: Return rendezvous circuit originating from this hidden
+/** Public function: Return rendezvous circuit originating from this hidden
  * service with rendezvous <b>cookie</b>. Return NULL if no such circuit is
  * found in the circuitmap. */
 origin_circuit_t *
@@ -439,7 +440,7 @@ hs_circuitmap_get_rend_circ_service_side(const uint8_t *cookie)
   return circ;
 }
 
-/* Public function: Return client-side rendezvous circuit with rendezvous
+/** Public function: Return client-side rendezvous circuit with rendezvous
  * <b>cookie</b>. It will look for circuits with the following purposes:
 
  * a) CIRCUIT_PURPOSE_C_REND_READY: Established rend circuit (received
@@ -472,7 +473,7 @@ hs_circuitmap_get_rend_circ_client_side(const uint8_t *cookie)
   return circ;
 }
 
-/*  Public function: Return client-side established rendezvous circuit with
+/**  Public function: Return client-side established rendezvous circuit with
  *  rendezvous <b>cookie</b>. It will look for circuits with the following
  *  purposes:
  *
@@ -514,7 +515,7 @@ hs_circuitmap_get_established_rend_circ_client_side(const uint8_t *cookie)
 
 /**** Public servide-side setters: */
 
-/* Public function: Register v2 intro circuit with key <b>digest</b> to the
+/** Public function: Register v2 intro circuit with key <b>digest</b> to the
  * circuitmap. */
 void
 hs_circuitmap_register_intro_circ_v2_service_side(origin_circuit_t *circ,
@@ -525,7 +526,7 @@ hs_circuitmap_register_intro_circ_v2_service_side(origin_circuit_t *circ,
                                  REND_TOKEN_LEN, digest);
 }
 
-/* Public function: Register v3 intro circuit with key <b>auth_key</b> to the
+/** Public function: Register v3 intro circuit with key <b>auth_key</b> to the
  * circuitmap. */
 void
 hs_circuitmap_register_intro_circ_v3_service_side(origin_circuit_t *circ,
@@ -536,7 +537,7 @@ hs_circuitmap_register_intro_circ_v3_service_side(origin_circuit_t *circ,
                                  ED25519_PUBKEY_LEN, auth_key->pubkey);
 }
 
-/* Public function: Register rendezvous circuit with key <b>cookie</b> to the
+/** Public function: Register rendezvous circuit with key <b>cookie</b> to the
  * circuitmap. */
 void
 hs_circuitmap_register_rend_circ_service_side(origin_circuit_t *circ,
@@ -547,7 +548,7 @@ hs_circuitmap_register_rend_circ_service_side(origin_circuit_t *circ,
                                  REND_TOKEN_LEN, cookie);
 }
 
-/* Public function: Register rendezvous circuit with key <b>cookie</b> to the
+/** Public function: Register rendezvous circuit with key <b>cookie</b> to the
  * client-side circuitmap. */
 void
 hs_circuitmap_register_rend_circ_client_side(origin_circuit_t *or_circ,
@@ -591,7 +592,7 @@ hs_circuitmap_remove_circuit(circuit_t *circ)
   circ->hs_token = NULL;
 }
 
-/* Public function: Initialize the global HS circuitmap. */
+/** Public function: Initialize the global HS circuitmap. */
 void
 hs_circuitmap_init(void)
 {
@@ -601,7 +602,7 @@ hs_circuitmap_init(void)
   HT_INIT(hs_circuitmap_ht, the_hs_circuitmap);
 }
 
-/* Public function: Free all memory allocated by the global HS circuitmap. */
+/** Public function: Free all memory allocated by the global HS circuitmap. */
 void
 hs_circuitmap_free_all(void)
 {
diff --git a/src/feature/hs/hs_common.c b/src/feature/hs/hs_common.c
index cf98bea32..75f4385ee 100644
--- a/src/feature/hs/hs_common.c
+++ b/src/feature/hs/hs_common.c
@@ -305,9 +305,9 @@ hs_get_next_time_period_num(time_t now)
   return hs_get_time_period_num(now) + 1;
 }
 
-/* Get the number of the _previous_ HS time period, given that the current time
- * is <b>now</b>. If <b>now</b> is not set, we try to get the time from a live
- * consensus. */
+/** Get the number of the _previous_ HS time period, given that the current
+ * time is <b>now</b>. If <b>now</b> is not set, we try to get the time from a
+ * live consensus. */
 uint64_t
 hs_get_previous_time_period_num(time_t now)
 {
@@ -725,7 +725,7 @@ build_blinded_key_param(const ed25519_public_key_t *pubkey,
   memwipe(nonce, 0, sizeof(nonce));
 }
 
-/* Using an ed25519 public key and version to build the checksum of an
+/** Using an ed25519 public key and version to build the checksum of an
  * address. Put in checksum_out. Format is:
  *    SHA3-256(".onion checksum" || PUBKEY || VERSION)
  *
diff --git a/src/feature/hs/hs_config.c b/src/feature/hs/hs_config.c
index 3b6caaec6..ed577daf7 100644
--- a/src/feature/hs/hs_config.c
+++ b/src/feature/hs/hs_config.c
@@ -34,7 +34,7 @@
 #include "lib/encoding/confline.h"
 #include "app/config/or_options_st.h"
 
-/* Using the given list of services, stage them into our global state. Every
+/** Using the given list of services, stage them into our global state. Every
  * service version are handled. This function can remove entries in the given
  * service_list.
  *
@@ -70,7 +70,7 @@ stage_services(smartlist_t *service_list)
   hs_service_stage_services(service_list);
 }
 
-/* Validate the given service against all service in the given list. If the
+/** Validate the given service against all service in the given list. If the
  * service is ephemeral, this function ignores it. Services with the same
  * directory path aren't allowed and will return an error. If a duplicate is
  * found, 1 is returned else 0 if none found. */
@@ -118,7 +118,7 @@ service_is_duplicate_in_list(const smartlist_t *service_list,
   return ret;
 }
 
-/* Helper function: Given an configuration option name, its value, a minimum
+/** Helper function: Given an configuration option name, its value, a minimum
  * min and a maxium max, parse the value as a uint64_t. On success, ok is set
  * to 1 and ret is the parsed value. On error, ok is set to 0 and ret must be
  * ignored. This function logs both on error and success. */
@@ -173,7 +173,7 @@ helper_parse_circuit_id_protocol(const char *key, const char *value, int *ok)
   return ret;
 }
 
-/* Return the service version by trying to learn it from the key on disk if
+/** Return the service version by trying to learn it from the key on disk if
  * any. If nothing is found, the current service configured version is
  * returned. */
 static int
@@ -191,7 +191,7 @@ config_learn_service_version(hs_service_t *service)
   return version;
 }
 
-/* Return true iff the given options starting at line_ for a hidden service
+/** Return true iff the given options starting at line_ for a hidden service
  * contains at least one invalid option. Each hidden service option don't
  * apply to all versions so this function can find out. The line_ MUST start
  * right after the HiddenServiceDir line of this service.
@@ -273,7 +273,7 @@ config_has_invalid_options(const config_line_t *line_,
   return ret;
 }
 
-/* Validate service configuration. This is used when loading the configuration
+/** Validate service configuration. This is used when loading the configuration
  * and once we've setup a service object, it's config object is passed to this
  * function for further validation. This does not validate service key
  * material. Return 0 if valid else -1 if invalid. */
@@ -304,7 +304,7 @@ config_validate_service(const hs_service_config_t *config)
   return -1;
 }
 
-/* Configuration funcion for a version 3 service. The line_ must be pointing
+/** Configuration funcion for a version 3 service. The line_ must be pointing
  * to the directive directly after a HiddenServiceDir. That way, when hitting
  * the next HiddenServiceDir line or reaching the end of the list of lines, we
  * know that we have to stop looking for more options. The given service
@@ -423,7 +423,7 @@ config_service_v3(const config_line_t *line_,
   return -1;
 }
 
-/* Configure a service using the given options in line_ and options. This is
+/** Configure a service using the given options in line_ and options. This is
  * called for any service regardless of its version which means that all
  * directives in this function are generic to any service version. This
  * function will also check the validity of the service directory path.
@@ -577,7 +577,7 @@ config_generic_service(const config_line_t *line_,
   return -1;
 }
 
-/* Configure a service using the given line and options. This function will
+/** Configure a service using the given line and options. This function will
  * call the corresponding configuration function for a specific service
  * version and validate the service against the other ones. On success, add
  * the service to the given list and return 0. On error, nothing is added to
@@ -663,7 +663,7 @@ config_service(const config_line_t *line, const or_options_t *options,
   return -1;
 }
 
-/* From a set of <b>options</b>, setup every hidden service found. Return 0 on
+/** From a set of <b>options</b>, setup every hidden service found. Return 0 on
  * success or -1 on failure. If <b>validate_only</b> is set, parse, warn and
  * return as normal, but don't actually change the configured services. */
 int
@@ -731,7 +731,7 @@ hs_config_service_all(const or_options_t *options, int validate_only)
   return ret;
 }
 
-/* From a set of <b>options</b>, setup every client authorization found.
+/** From a set of <b>options</b>, setup every client authorization found.
  * Return 0 on success or -1 on failure. If <b>validate_only</b> is set,
  * parse, warn and return as normal, but don't actually change the
  * configured state. */
diff --git a/src/feature/hs/hs_control.c b/src/feature/hs/hs_control.c
index abb421345..461be3e1e 100644
--- a/src/feature/hs/hs_control.c
+++ b/src/feature/hs/hs_control.c
@@ -20,7 +20,7 @@
 #include "feature/nodelist/node_st.h"
 #include "feature/nodelist/routerstatus_st.h"
 
-/* Send on the control port the "HS_DESC REQUESTED [...]" event.
+/** Send on the control port the "HS_DESC REQUESTED [...]" event.
  *
  * The onion_pk is the onion service public key, base64_blinded_pk is the
  * base64 encoded blinded key for the service and hsdir_rs is the routerstatus
@@ -57,7 +57,7 @@ hs_control_desc_event_requested(const ed25519_public_key_t *onion_pk,
   memwipe(onion_address, 0, sizeof(onion_address));
 }
 
-/* Send on the control port the "HS_DESC FAILED [...]" event.
+/** Send on the control port the "HS_DESC FAILED [...]" event.
  *
  * Using a directory connection identifier, the HSDir identity digest and a
  * reason for the failure. None can be NULL. */
@@ -81,7 +81,7 @@ hs_control_desc_event_failed(const hs_ident_dir_conn_t *ident,
                                        hsdir_id_digest, reason);
 }
 
-/* Send on the control port the "HS_DESC RECEIVED [...]" event.
+/** Send on the control port the "HS_DESC RECEIVED [...]" event.
  *
  * Using a directory connection identifier and the HSDir identity digest.
  * None can be NULL. */
@@ -103,7 +103,7 @@ hs_control_desc_event_received(const hs_ident_dir_conn_t *ident,
                                          hsdir_id_digest);
 }
 
-/* Send on the control port the "HS_DESC CREATED [...]" event.
+/** Send on the control port the "HS_DESC CREATED [...]" event.
  *
  * Using the onion address of the descriptor's service and the blinded public
  * key of the descriptor as a descriptor ID. None can be NULL. */
@@ -124,7 +124,7 @@ hs_control_desc_event_created(const char *onion_address,
   control_event_hs_descriptor_created(onion_address, base64_blinded_pk, -1);
 }
 
-/* Send on the control port the "HS_DESC UPLOAD [...]" event.
+/** Send on the control port the "HS_DESC UPLOAD [...]" event.
  *
  * Using the onion address of the descriptor's service, the HSDir identity
  * digest, the blinded public key of the descriptor as a descriptor ID and the
@@ -151,7 +151,7 @@ hs_control_desc_event_upload(const char *onion_address,
                                              DIGEST256_LEN));
 }
 
-/* Send on the control port the "HS_DESC UPLOADED [...]" event.
+/** Send on the control port the "HS_DESC UPLOADED [...]" event.
  *
  * Using the directory connection identifier and the HSDir identity digest.
  * None can be NULL. */
@@ -169,7 +169,7 @@ hs_control_desc_event_uploaded(const hs_ident_dir_conn_t *ident,
   control_event_hs_descriptor_uploaded(hsdir_id_digest, onion_address);
 }
 
-/* Send on the control port the "HS_DESC_CONTENT [...]" event.
+/** Send on the control port the "HS_DESC_CONTENT [...]" event.
  *
  * Using the directory connection identifier, the HSDir identity digest and
  * the body of the descriptor (as it was received from the directory). None
@@ -193,7 +193,7 @@ hs_control_desc_event_content(const hs_ident_dir_conn_t *ident,
                                       hsdir_id_digest, body);
 }
 
-/* Handle the "HSPOST [...]" command. The body is an encoded descriptor for
+/** Handle the "HSPOST [...]" command. The body is an encoded descriptor for
  * the given onion_address. The descriptor will be uploaded to each directory
  * in hsdirs_rs. If NULL, the responsible directories for the current time
  * period will be selected.
@@ -248,7 +248,7 @@ hs_control_hspost_command(const char *body, const char *onion_address,
   return ret;
 }
 
-/* With a given <b>onion_identity_pk</b>, fetch its descriptor, optionally
+/** With a given <b>onion_identity_pk</b>, fetch its descriptor, optionally
  * using the list of directory servers given in <b>hsdirs</b>, or a random
  * server if it is NULL. This function calls hs_client_launch_v3_desc_fetch().
  */
diff --git a/src/feature/hs/hs_dos.c b/src/feature/hs/hs_dos.c
index d36ee97e6..529955b0e 100644
--- a/src/feature/hs/hs_dos.c
+++ b/src/feature/hs/hs_dos.c
@@ -31,21 +31,21 @@
 
 #include "feature/hs/hs_dos.h"
 
-/* Default value of the allowed INTRODUCE2 cell rate per second. Above that
+/** Default value of the allowed INTRODUCE2 cell rate per second. Above that
  * value per second, the introduction is denied. */
 #define HS_DOS_INTRODUCE_DEFAULT_CELL_RATE_PER_SEC 25
 
-/* Default value of the allowed INTRODUCE2 cell burst per second. This is the
+/** Default value of the allowed INTRODUCE2 cell burst per second. This is the
  * maximum value a token bucket has per second. We thus allow up to this value
  * of INTRODUCE2 cell per second but the bucket is refilled by the rate value
  * but never goes above that burst value. */
 #define HS_DOS_INTRODUCE_DEFAULT_CELL_BURST_PER_SEC 200
 
-/* Default value of the consensus parameter enabling or disabling the
+/** Default value of the consensus parameter enabling or disabling the
  * introduction DoS defense. Disabled by default. */
 #define HS_DOS_INTRODUCE_ENABLED_DEFAULT 0
 
-/* INTRODUCE2 rejected request counter. */
+/** INTRODUCE2 rejected request counter. */
 static uint64_t intro2_rejected_count = 0;
 
 /* Consensus parameters. The ESTABLISH_INTRO DoS cell extension have higher
@@ -65,7 +65,7 @@ get_intro2_enable_consensus_param(const networkstatus_t *ns)
                                  HS_DOS_INTRODUCE_ENABLED_DEFAULT, 0, 1);
 }
 
-/* Return the parameter for the introduction rate per sec. */
+/** Return the parameter for the introduction rate per sec. */
 STATIC uint32_t
 get_intro2_rate_consensus_param(const networkstatus_t *ns)
 {
@@ -74,7 +74,7 @@ get_intro2_rate_consensus_param(const networkstatus_t *ns)
                                  0, INT32_MAX);
 }
 
-/* Return the parameter for the introduction burst per sec. */
+/** Return the parameter for the introduction burst per sec. */
 STATIC uint32_t
 get_intro2_burst_consensus_param(const networkstatus_t *ns)
 {
@@ -83,7 +83,7 @@ get_intro2_burst_consensus_param(const networkstatus_t *ns)
                                  0, INT32_MAX);
 }
 
-/* Go over all introduction circuit relay side and adjust their rate/burst
+/** Go over all introduction circuit relay side and adjust their rate/burst
  * values using the global parameters. This is called right after the
  * consensus parameters might have changed. */
 static void
@@ -105,7 +105,7 @@ update_intro_circuits(void)
   smartlist_free(intro_circs);
 }
 
-/* Set consensus parameters. */
+/** Set consensus parameters. */
 static void
 set_consensus_parameters(const networkstatus_t *ns)
 {
@@ -125,7 +125,7 @@ set_consensus_parameters(const networkstatus_t *ns)
  * Public API.
  */
 
-/* Initialize the INTRODUCE2 token bucket for the DoS defenses using the
+/** Initialize the INTRODUCE2 token bucket for the DoS defenses using the
  * consensus/default values. We might get a cell extension that changes those
  * later but if we don't, the default or consensus parameters are used. */
 void
@@ -141,7 +141,7 @@ hs_dos_setup_default_intro2_defenses(or_circuit_t *circ)
                         (uint32_t) approx_time());
 }
 
-/* Called when the consensus has changed. We might have new consensus
+/** Called when the consensus has changed. We might have new consensus
  * parameters to look at. */
 void
 hs_dos_consensus_has_changed(const networkstatus_t *ns)
@@ -155,7 +155,7 @@ hs_dos_consensus_has_changed(const networkstatus_t *ns)
   set_consensus_parameters(ns);
 }
 
-/* Return true iff an INTRODUCE2 cell can be sent on the given service
+/** Return true iff an INTRODUCE2 cell can be sent on the given service
  * introduction circuit. */
 bool
 hs_dos_can_send_intro2(or_circuit_t *s_intro_circ)
@@ -206,14 +206,14 @@ hs_dos_can_send_intro2(or_circuit_t *s_intro_circ)
   return true;
 }
 
-/* Return rolling count of rejected INTRO2. */
+/** Return rolling count of rejected INTRO2. */
 uint64_t
 hs_dos_get_intro2_rejected_count(void)
 {
   return intro2_rejected_count;
 }
 
-/* Initialize the onion service Denial of Service subsystem. */
+/** Initialize the onion service Denial of Service subsystem. */
 void
 hs_dos_init(void)
 {
diff --git a/src/feature/hs/hs_intropoint.c b/src/feature/hs/hs_intropoint.c
index fe8486b1a..c3889004f 100644
--- a/src/feature/hs/hs_intropoint.c
+++ b/src/feature/hs/hs_intropoint.c
@@ -147,7 +147,7 @@ verify_establish_intro_cell(const trn_cell_establish_intro_t *cell,
   return 0;
 }
 
-/* Send an INTRO_ESTABLISHED cell to <b>circ</b>. */
+/** Send an INTRO_ESTABLISHED cell to <b>circ</b>. */
 MOCK_IMPL(int,
 hs_intro_send_intro_established_cell,(or_circuit_t *circ))
 {
@@ -182,7 +182,7 @@ hs_intro_send_intro_established_cell,(or_circuit_t *circ))
   return ret;
 }
 
-/* Validate the cell DoS extension parameters. Return true iff they've been
+/** Validate the cell DoS extension parameters. Return true iff they've been
  * bound check and can be used. Else return false. See proposal 305 for
  * details and reasons about this validation. */
 STATIC bool
@@ -244,7 +244,7 @@ cell_dos_extension_parameters_are_valid(uint64_t intro2_rate_per_sec,
   return ret;
 }
 
-/* Parse the cell DoS extension and apply defenses on the given circuit if
+/** Parse the cell DoS extension and apply defenses on the given circuit if
  * validation passes. If the cell extension is malformed or contains unusable
  * values, the DoS defenses is disabled on the circuit. */
 static void
@@ -321,7 +321,7 @@ handle_establish_intro_cell_dos_extension(
   return;
 }
 
-/* Parse every cell extension in the given ESTABLISH_INTRO cell. */
+/** Parse every cell extension in the given ESTABLISH_INTRO cell. */
 static void
 handle_establish_intro_cell_extensions(
                             const trn_cell_establish_intro_t *parsed_cell,
@@ -457,7 +457,7 @@ handle_establish_intro(or_circuit_t *circ, const uint8_t *request,
   return retval;
 }
 
-/* Return True if circuit is suitable for being an intro circuit. */
+/** Return True if circuit is suitable for being an intro circuit. */
 static int
 circuit_is_suitable_intro_point(const or_circuit_t *circ,
                                 const char *log_cell_type_str)
@@ -482,14 +482,14 @@ circuit_is_suitable_intro_point(const or_circuit_t *circ,
   return 1;
 }
 
-/* Return True if circuit is suitable for being service-side intro circuit. */
+/** Return True if circuit is suitable for being service-side intro circuit. */
 int
 hs_intro_circuit_is_suitable_for_establish_intro(const or_circuit_t *circ)
 {
   return circuit_is_suitable_intro_point(circ, "ESTABLISH_INTRO");
 }
 
-/* We just received an ESTABLISH_INTRO cell in <b>circ</b>. Figure out of it's
+/** We just received an ESTABLISH_INTRO cell in <b>circ</b>. Figure out of it's
  * a legacy or a next gen cell, and pass it to the appropriate handler. */
 int
 hs_intro_received_establish_intro(or_circuit_t *circ, const uint8_t *request,
@@ -523,7 +523,7 @@ hs_intro_received_establish_intro(or_circuit_t *circ, const uint8_t *request,
   return -1;
 }
 
-/* Send an INTRODUCE_ACK cell onto the circuit <b>circ</b> with the status
+/** Send an INTRODUCE_ACK cell onto the circuit <b>circ</b> with the status
  * value in <b>status</b>. Depending on the status, it can be ACK or a NACK.
  * Return 0 on success else a negative value on error which will close the
  * circuit. */
@@ -567,7 +567,7 @@ send_introduce_ack_cell(or_circuit_t *circ, uint16_t status)
   return ret;
 }
 
-/* Validate a parsed INTRODUCE1 <b>cell</b>. Return 0 if valid or else a
+/** Validate a parsed INTRODUCE1 <b>cell</b>. Return 0 if valid or else a
  * negative value for an invalid cell that should be NACKed. */
 STATIC int
 validate_introduce1_parsed_cell(const trn_cell_introduce1_t *cell)
@@ -613,7 +613,7 @@ validate_introduce1_parsed_cell(const trn_cell_introduce1_t *cell)
   return -1;
 }
 
-/* We just received a non legacy INTRODUCE1 cell on <b>client_circ</b> with
+/** We just received a non legacy INTRODUCE1 cell on <b>client_circ</b> with
  * the payload in <b>request</b> of size <b>request_len</b>. Return 0 if
  * everything went well, or -1 if an error occurred. This function is in charge
  * of sending back an INTRODUCE_ACK cell and will close client_circ on error.
@@ -712,7 +712,7 @@ handle_introduce1(or_circuit_t *client_circ, const uint8_t *request,
   return ret;
 }
 
-/* Identify if the encoded cell we just received is a legacy one or not. The
+/** Identify if the encoded cell we just received is a legacy one or not. The
  * <b>request</b> should be at least DIGEST_LEN bytes long. */
 STATIC int
 introduce1_cell_is_legacy(const uint8_t *request)
@@ -729,7 +729,7 @@ introduce1_cell_is_legacy(const uint8_t *request)
   return 0;
 }
 
-/* Return true iff the circuit <b>circ</b> is suitable for receiving an
+/** Return true iff the circuit <b>circ</b> is suitable for receiving an
  * INTRODUCE1 cell. */
 STATIC int
 circuit_is_suitable_for_introduce1(const or_circuit_t *circ)
@@ -760,7 +760,7 @@ circuit_is_suitable_for_introduce1(const or_circuit_t *circ)
   return 1;
 }
 
-/* We just received an INTRODUCE1 cell on <b>circ</b>. Figure out which type
+/** We just received an INTRODUCE1 cell on <b>circ</b>. Figure out which type
  * it is and pass it to the appropriate handler. Return 0 on success else a
  * negative value and the circuit is closed. */
 int
@@ -804,8 +804,8 @@ hs_intro_received_introduce1(or_circuit_t *circ, const uint8_t *request,
   return -1;
 }
 
-/* Clear memory allocated by the given intropoint object ip (but don't free the
- * object itself). */
+/** Clear memory allocated by the given intropoint object ip (but don't free
+ * the object itself). */
 void
 hs_intropoint_clear(hs_intropoint_t *ip)
 {
diff --git a/src/feature/hs/hs_intropoint.h b/src/feature/hs/hs_intropoint.h
index 94ebf021e..f4d7ad263 100644
--- a/src/feature/hs/hs_intropoint.h
+++ b/src/feature/hs/hs_intropoint.h
@@ -12,15 +12,15 @@
 #include "lib/crypt_ops/crypto_curve25519.h"
 #include "feature/nodelist/torcert.h"
 
-/* Object containing introduction point common data between the service and
+/** Object containing introduction point common data between the service and
  * the client side. */
 typedef struct hs_intropoint_t {
-  /* Does this intro point only supports legacy ID ?. */
+  /** Does this intro point only supports legacy ID ?. */
   unsigned int is_only_legacy : 1;
 
-  /* Authentication key certificate from the descriptor. */
+  /** Authentication key certificate from the descriptor. */
   tor_cert_t *auth_key_cert;
-  /* A list of link specifier. */
+  /** A list of link specifier. */
   smartlist_t *link_specifiers;
 } hs_intropoint_t;
 
@@ -64,4 +64,3 @@ STATIC bool cell_dos_extension_parameters_are_valid(
 #endif /* defined(HS_INTROPOINT_PRIVATE) */
 
 #endif /* !defined(TOR_HS_INTRO_H) */
-
diff --git a/src/feature/hs/hs_service.c b/src/feature/hs/hs_service.c
index d0fb77fda..5693cdb0f 100644
--- a/src/feature/hs/hs_service.c
+++ b/src/feature/hs/hs_service.c
@@ -509,7 +509,7 @@ service_intro_point_new(const node_t *node)
   return NULL;
 }
 
-/* Add the given intro point object to the given intro point map. The intro
+/** Add the given intro point object to the given intro point map. The intro
  * point MUST have its RSA encryption key set if this is a legacy type or the
  * authentication key set otherwise. */
 STATIC void
@@ -1076,7 +1076,7 @@ load_service_keys(hs_service_t *service)
   return ret;
 }
 
-/* Check if the client file name is valid or not. Return 1 if valid,
+/** Check if the client file name is valid or not. Return 1 if valid,
  * otherwise return 0. */
 STATIC int
 client_filename_is_valid(const char *filename)
@@ -1737,7 +1737,7 @@ build_service_desc_encrypted(const hs_service_t *service,
   return 0;
 }
 
-/* Populate the descriptor superencrypted section from the given service
+/** Populate the descriptor superencrypted section from the given service
  * object. This will generate a valid list of hs_desc_authorized_client_t
  * of clients that are authorized to use the service. Return 0 on success
  * else -1 on error. */
@@ -2637,7 +2637,7 @@ run_build_descriptor_event(time_t now)
   update_all_descriptors_intro_points(now);
 }
 
-/* For the given service, launch any intro point circuits that could be
+/** For the given service, launch any intro point circuits that could be
  * needed. This considers every descriptor of the service. */
 static void
 launch_intro_point_circuits(hs_service_t *service)
diff --git a/src/feature/hs/hs_service.h b/src/feature/hs/hs_service.h
index 193e08546..6c929c7ff 100644
--- a/src/feature/hs/hs_service.h
+++ b/src/feature/hs/hs_service.h
@@ -29,6 +29,7 @@
 /** As described in the specification, service publishes their next descriptor
  * at a random time between those two values (in seconds). */
 #define HS_SERVICE_NEXT_UPLOAD_TIME_MIN (60 * 60)
+/** Maximum interval for uploading next descriptor (in seconds). */
 #define HS_SERVICE_NEXT_UPLOAD_TIME_MAX (120 * 60)
 
 /** Service side introduction point. */
@@ -316,6 +317,11 @@ void hs_service_free_all(void);
 /* Service new/free functions. */
 hs_service_t *hs_service_new(const or_options_t *options);
 void hs_service_free_(hs_service_t *service);
+/**
+ * @copydoc hs_service_free_
+ *
+ * Additionally, set the pointer <b>s</b> to NULL.
+ **/
 #define hs_service_free(s) FREE_AND_NULL(hs_service_t, hs_service_free_, (s))
 
 MOCK_DECL(unsigned int, hs_service_get_num_services,(void));
diff --git a/src/feature/hs/hsdir_index_st.h b/src/feature/hs/hsdir_index_st.h
index 34ff84f91..0a0ac8ae6 100644
--- a/src/feature/hs/hsdir_index_st.h
+++ b/src/feature/hs/hsdir_index_st.h
@@ -12,16 +12,17 @@
 #ifndef HSDIR_INDEX_ST_H
 #define HSDIR_INDEX_ST_H
 
-/* Hidden service directory index used in a node_t which is set once we set
+/** Hidden service directory index used in a node_t which is set once we set
  * the consensus. */
 struct hsdir_index_t {
-  /* HSDir index to use when fetching a descriptor. */
+  /** HSDir index to use when fetching a descriptor. */
   uint8_t fetch[DIGEST256_LEN];
 
-  /* HSDir index used by services to store their first and second
+  /** HSDir index used by services to store their first and second
    * descriptor. The first descriptor is chronologically older than the second
    * one and uses older TP and SRV values. */
   uint8_t store_first[DIGEST256_LEN];
+  /** Newer index, for second descriptor. */
   uint8_t store_second[DIGEST256_LEN];
 };
 
diff --git a/src/feature/hs_common/replaycache.h b/src/feature/hs_common/replaycache.h
index 01f5e600c..812a05d26 100644
--- a/src/feature/hs_common/replaycache.h
+++ b/src/feature/hs_common/replaycache.h
@@ -14,16 +14,16 @@ typedef struct replaycache_t replaycache_t;
 #ifdef REPLAYCACHE_PRIVATE
 
 struct replaycache_t {
-  /* Scrub interval */
+  /** Scrub interval */
   time_t scrub_interval;
-  /* Last scrubbed */
+  /** Last scrubbed */
   time_t scrubbed;
-  /*
+  /**
    * Horizon
    * (don't return true on digests in the cache but older than this)
    */
   time_t horizon;
-  /*
+  /**
    * Digest map: keys are digests, values are times the digest was last seen
    */
   digest256map_t *digests_seen;
@@ -34,6 +34,11 @@ struct replaycache_t {
 /* replaycache_t free/new */
 
 void replaycache_free_(replaycache_t *r);
+/**
+ * @copydoc replaycache_free_
+ *
+ * Additionally, set the pointer <b>r</b> to NULL.
+ **/
 #define replaycache_free(r) \
   FREE_AND_NULL(replaycache_t, replaycache_free_, (r))
 replaycache_t * replaycache_new(time_t horizon, time_t interval);
diff --git a/src/feature/hs_common/shared_random_client.c b/src/feature/hs_common/shared_random_client.c
index 5772034c6..f5328e6e1 100644
--- a/src/feature/hs_common/shared_random_client.c
+++ b/src/feature/hs_common/shared_random_client.c
@@ -18,7 +18,7 @@
 
 #include "feature/nodelist/networkstatus_st.h"
 
-/* Convert a given srv object to a string for the control port. This doesn't
+/** Convert a given srv object to a string for the control port. This doesn't
  * fail and the srv object MUST be valid. */
 static char *
 srv_to_control_string(const sr_srv_t *srv)
@@ -32,7 +32,7 @@ srv_to_control_string(const sr_srv_t *srv)
   return srv_str;
 }
 
-/* Return the voting interval of the tor vote subsystem. */
+/** Return the voting interval of the tor vote subsystem. */
 int
 get_voting_interval(void)
 {
@@ -51,7 +51,7 @@ get_voting_interval(void)
   return interval;
 }
 
-/* Given the current consensus, return the start time of the current round of
+/** Given the current consensus, return the start time of the current round of
  * the SR protocol. For example, if it's 23:47:08, the current round thus
  * started at 23:47:00 for a voting interval of 10 seconds.
  *
@@ -78,7 +78,7 @@ get_start_time_of_current_round(void)
  * Public API
  */
 
-/* Encode the given shared random value and put it in dst. Destination
+/** Encode the given shared random value and put it in dst. Destination
  * buffer must be at least SR_SRV_VALUE_BASE64_LEN plus the NULL byte. */
 void
 sr_srv_encode(char *dst, size_t dst_len, const sr_srv_t *srv)
@@ -99,7 +99,7 @@ sr_srv_encode(char *dst, size_t dst_len, const sr_srv_t *srv)
   strlcpy(dst, buf, dst_len);
 }
 
-/* Return the current SRV string representation for the control port. Return a
+/** Return the current SRV string representation for the control port. Return a
  * newly allocated string on success containing the value else "" if not found
  * or if we don't have a valid consensus yet. */
 char *
@@ -115,7 +115,7 @@ sr_get_current_for_control(void)
   return srv_str;
 }
 
-/* Return the previous SRV string representation for the control port. Return
+/** Return the previous SRV string representation for the control port. Return
  * a newly allocated string on success containing the value else "" if not
  * found or if we don't have a valid consensus yet. */
 char *
@@ -131,7 +131,7 @@ sr_get_previous_for_control(void)
   return srv_str;
 }
 
-/* Return current shared random value from the latest consensus. Caller can
+/** Return current shared random value from the latest consensus. Caller can
  * NOT keep a reference to the returned pointer. Return NULL if none. */
 const sr_srv_t *
 sr_get_current(const networkstatus_t *ns)
@@ -154,7 +154,7 @@ sr_get_current(const networkstatus_t *ns)
   return NULL;
 }
 
-/* Return previous shared random value from the latest consensus. Caller can
+/** Return previous shared random value from the latest consensus. Caller can
  * NOT keep a reference to the returned pointer. Return NULL if none. */
 const sr_srv_t *
 sr_get_previous(const networkstatus_t *ns)
@@ -177,7 +177,7 @@ sr_get_previous(const networkstatus_t *ns)
   return NULL;
 }
 
-/* Parse a list of arguments from a SRV value either from a vote, consensus
+/** Parse a list of arguments from a SRV value either from a vote, consensus
  * or from our disk state and return a newly allocated srv object. NULL is
  * returned on error.
  *
@@ -290,4 +290,3 @@ sr_state_get_protocol_run_duration(void)
   int total_protocol_rounds = SHARED_RANDOM_N_ROUNDS * SHARED_RANDOM_N_PHASES;
   return total_protocol_rounds * get_voting_interval();
 }
-

_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits