hs_client.[ch]: fix doxygen comments by using /**.

src/feature/hs/hs_client.c

@@ -43,13 +43,13 @@
 #include "core/or/extend_info_st.h"
 #include "core/or/origin_circuit_st.h"
 
-/* Client-side authorizations for hidden services; map of service identity
+/** Client-side authorizations for hidden services; map of service identity
  * public key to hs_client_service_authorization_t *. */
 static digest256map_t *client_auths = NULL;
 
 #include "trunnel/hs/cell_introduce1.h"
 
-/* Return a human-readable string for the client fetch status code. */
+/** Return a human-readable string for the client fetch status code. */
 static const char *
 fetch_status_to_string(hs_client_fetch_status_t status)
 {
@@ -73,7 +73,7 @@ fetch_status_to_string(hs_client_fetch_status_t status)
   }
 }
 
-/* Return true iff tor should close the SOCKS request(s) for the descriptor
+/** Return true iff tor should close the SOCKS request(s) for the descriptor
  * fetch that ended up with this given status code. */
 static int
 fetch_status_should_close_socks(hs_client_fetch_status_t status)
@@ -100,7 +100,7 @@ fetch_status_should_close_socks(hs_client_fetch_status_t status)
   return 1;
 }
 
-/* Cancel all descriptor fetches currently in progress. */
+/** Cancel all descriptor fetches currently in progress. */
 static void
 cancel_descriptor_fetches(void)
 {
@@ -124,7 +124,7 @@ cancel_descriptor_fetches(void)
   log_info(LD_REND, "Hidden service client descriptor fetches cancelled.");
 }
 
-/* Get all connections that are waiting on a circuit and flag them back to
+/** Get all connections that are waiting on a circuit and flag them back to
  * waiting for a hidden service descriptor for the given service key
  * service_identity_pk. */
 static void
@@ -151,7 +151,7 @@ flag_all_conn_wait_desc(const ed25519_public_key_t *service_identity_pk)
   smartlist_free(conns);
 }
 
-/* Remove tracked HSDir requests from our history for this hidden service
+/** Remove tracked HSDir requests from our history for this hidden service
  * identity public key. */
 static void
 purge_hid_serv_request(const ed25519_public_key_t *identity_pk)
@@ -172,7 +172,7 @@ purge_hid_serv_request(const ed25519_public_key_t *identity_pk)
   hs_purge_hid_serv_from_last_hid_serv_requests(base64_blinded_pk);
 }
 
-/* Return true iff there is at least one pending directory descriptor request
+/** Return true iff there is at least one pending directory descriptor request
  * for the service identity_pk. */
 static int
 directory_request_is_pending(const ed25519_public_key_t *identity_pk)
@@ -200,7 +200,7 @@ directory_request_is_pending(const ed25519_public_key_t *identity_pk)
   return ret;
 }
 
-/* Helper function that changes the state of an entry connection to waiting
+/** Helper function that changes the state of an entry connection to waiting
  * for a circuit. For this to work properly, the connection timestamps are set
  * to now and the connection is then marked as pending for a circuit. */
 static void
@@ -220,7 +220,7 @@ mark_conn_as_waiting_for_circuit(connection_t *conn, time_t now)
   connection_ap_mark_as_pending_circuit(TO_ENTRY_CONN(conn));
 }
 
-/* We failed to fetch a descriptor for the service with <b>identity_pk</b>
+/** We failed to fetch a descriptor for the service with <b>identity_pk</b>
  * because of <b>status</b>. Find all pending SOCKS connections for this
  * service that are waiting on the descriptor and close them with
  * <b>reason</b>. */
@@ -265,7 +265,7 @@ close_all_socks_conns_waiting_for_desc(const ed25519_public_key_t *identity_pk,
   smartlist_free(conns);
 }
 
-/* Find all pending SOCKS connection waiting for a descriptor and retry them
+/** Find all pending SOCKS connection waiting for a descriptor and retry them
  * all. This is called when the directory information changed. */
 STATIC void
 retry_all_socks_conn_waiting_for_desc(void)
@@ -321,7 +321,7 @@ retry_all_socks_conn_waiting_for_desc(void)
   smartlist_free(conns);
 }
 
-/* A v3 HS circuit successfully connected to the hidden service. Update the
+/** A v3 HS circuit successfully connected to the hidden service. Update the
  * stream state at <b>hs_conn_ident</b> appropriately. */
 static void
 note_connection_attempt_succeeded(const hs_ident_edge_conn_t *hs_conn_ident)
@@ -343,7 +343,7 @@ note_connection_attempt_succeeded(const hs_ident_edge_conn_t *hs_conn_ident)
    * will be reset and thus possible to be retried. */
 }
 
-/* Given the pubkey of a hidden service in <b>onion_identity_pk</b>, fetch its
+/** Given the pubkey of a hidden service in <b>onion_identity_pk</b>, fetch its
  * descriptor by launching a dir connection to <b>hsdir</b>. Return a
  * hs_client_fetch_status_t status code depending on how it went. */
 static hs_client_fetch_status_t
@@ -451,7 +451,7 @@ fetch_v3_desc, (const ed25519_public_key_t *onion_identity_pk))
   return directory_launch_v3_desc_fetch(onion_identity_pk, hsdir_rs);
 }
 
-/* With a given <b>onion_identity_pk</b>, fetch its descriptor. If
+/** With a given <b>onion_identity_pk</b>, fetch its descriptor. If
  * <b>hsdirs</b> is specified, use the directory servers specified in the list.
  * Else, use a random server. */
 void
@@ -469,7 +469,7 @@ hs_client_launch_v3_desc_fetch(const ed25519_public_key_t *onion_identity_pk,
   }
 }
 
-/* Make sure that the given v3 origin circuit circ is a valid correct
+/** Make sure that the given v3 origin circuit circ is a valid correct
  * introduction circuit. This will BUG() on any problems and hard assert if
  * the anonymity of the circuit is not ok. Return 0 on success else -1 where
  * the circuit should be mark for closed immediately. */
@@ -498,7 +498,7 @@ intro_circ_is_ok(const origin_circuit_t *circ)
   return ret;
 }
 
-/* Find a descriptor intro point object that matches the given ident in the
+/** Find a descriptor intro point object that matches the given ident in the
  * given descriptor desc. Return NULL if not found. */
 static const hs_desc_intro_point_t *
 find_desc_intro_point_by_ident(const hs_ident_circuit_t *ident,
@@ -521,7 +521,7 @@ find_desc_intro_point_by_ident(const hs_ident_circuit_t *ident,
   return intro_point;
 }
 
-/* Find a descriptor intro point object from the descriptor object desc that
+/** Find a descriptor intro point object from the descriptor object desc that
  * matches the given legacy identity digest in legacy_id. Return NULL if not
  * found. */
 static hs_desc_intro_point_t *
@@ -559,7 +559,7 @@ find_desc_intro_point_by_legacy_id(const char *legacy_id,
   return ret_ip;
 }
 
-/* Send an INTRODUCE1 cell along the intro circuit and populate the rend
+/** Send an INTRODUCE1 cell along the intro circuit and populate the rend
  * circuit identifier with the needed key material for the e2e encryption.
  * Return 0 on success, -1 if there is a transient error such that an action
  * has been taken to recover and -2 if there is a permanent error indicating
@@ -671,7 +671,7 @@ send_introduce1(origin_circuit_t *intro_circ,
   return status;
 }
 
-/* Using the introduction circuit circ, setup the authentication key of the
+/** Using the introduction circuit circ, setup the authentication key of the
  * intro point this circuit has extended to. */
 static void
 setup_intro_circ_auth_key(origin_circuit_t *circ)
@@ -706,7 +706,7 @@ setup_intro_circ_auth_key(origin_circuit_t *circ)
   return;
 }
 
-/* Called when an introduction circuit has opened. */
+/** Called when an introduction circuit has opened. */
 static void
 client_intro_circ_has_opened(origin_circuit_t *circ)
 {
@@ -723,7 +723,7 @@ client_intro_circ_has_opened(origin_circuit_t *circ)
   connection_ap_attach_pending(1);
 }
 
-/* Called when a rendezvous circuit has opened. */
+/** Called when a rendezvous circuit has opened. */
 static void
 client_rendezvous_circ_has_opened(origin_circuit_t *circ)
 {
@@ -757,7 +757,7 @@ client_rendezvous_circ_has_opened(origin_circuit_t *circ)
   }
 }
 
-/* This is an helper function that convert a descriptor intro point object ip
+/** This is an helper function that convert a descriptor intro point object ip
  * to a newly allocated extend_info_t object fully initialized. Return NULL if
  * we can't convert it for which chances are that we are missing or malformed
  * link specifiers. */
@@ -775,7 +775,7 @@ desc_intro_point_to_extend_info(const hs_desc_intro_point_t *ip)
   return ei;
 }
 
-/* Return true iff the intro point ip for the service service_pk is usable.
+/** Return true iff the intro point ip for the service service_pk is usable.
  * This function checks if the intro point is in the client intro state cache
  * and checks at the failures. It is considered usable if:
  *   - No error happened (INTRO_POINT_FAILURE_GENERIC)
@@ -820,7 +820,7 @@ intro_point_is_usable(const ed25519_public_key_t *service_pk,
   return 0;
 }
 
-/* Using a descriptor desc, return a newly allocated extend_info_t object of a
+/** Using a descriptor desc, return a newly allocated extend_info_t object of a
  * randomly picked introduction point from its list. Return NULL if none are
  * usable. */
 STATIC extend_info_t *
@@ -925,7 +925,7 @@ client_get_random_intro(const ed25519_public_key_t *service_pk)
   return ei;
 }
 
-/* For this introduction circuit, we'll look at if we have any usable
+/** For this introduction circuit, we'll look at if we have any usable
  * introduction point left for this service. If so, we'll use the circuit to
  * re-extend to a new intro point. Else, we'll close the circuit and its
  * corresponding rendezvous circuit. Return 0 if we are re-extending else -1
@@ -982,7 +982,7 @@ close_or_reextend_intro_circ(origin_circuit_t *intro_circ)
   return ret;
 }
 
-/* Called when we get an INTRODUCE_ACK success status code. Do the appropriate
+/** Called when we get an INTRODUCE_ACK success status code. Do the appropriate
  * actions for the rendezvous point and finally close intro_circ. */
 static void
 handle_introduce_ack_success(origin_circuit_t *intro_circ)
@@ -1028,7 +1028,7 @@ handle_introduce_ack_success(origin_circuit_t *intro_circ)
   return;
 }
 
-/* Called when we get an INTRODUCE_ACK failure status code. Depending on our
+/** Called when we get an INTRODUCE_ACK failure status code. Depending on our
  * failure cache status, either close the circuit or re-extend to a new
  * introduction point. */
 static void
@@ -1050,7 +1050,7 @@ handle_introduce_ack_bad(origin_circuit_t *circ, int status)
                                    INTRO_POINT_FAILURE_GENERIC);
 }
 
-/* Called when we get an INTRODUCE_ACK on the intro circuit circ. The encoded
+/** Called when we get an INTRODUCE_ACK on the intro circuit circ. The encoded
  * cell is in payload of length payload_len. Return 0 on success else a
  * negative value. The circuit is either close or reuse to re-extend to a new
  * introduction point. */
@@ -1089,7 +1089,7 @@ handle_introduce_ack(origin_circuit_t *circ, const uint8_t *payload,
   return ret;
 }
 
-/* Called when we get a RENDEZVOUS2 cell on the rendezvous circuit circ. The
+/** Called when we get a RENDEZVOUS2 cell on the rendezvous circuit circ. The
  * encoded cell is in payload of length payload_len. Return 0 on success or a
  * negative value on error. On error, the circuit is marked for close. */
 STATIC int
@@ -1151,7 +1151,7 @@ handle_rendezvous2(origin_circuit_t *circ, const uint8_t *payload,
   return ret;
 }
 
-/* Return true iff the client can fetch a descriptor for this service public
+/** Return true iff the client can fetch a descriptor for this service public
  * identity key and status_out if not NULL is untouched. If the client can
  * _not_ fetch the descriptor and if status_out is not NULL, it is set with
  * the fetch status code. */
@@ -1218,7 +1218,7 @@ can_client_refetch_desc(const ed25519_public_key_t *identity_pk,
   return 0;
 }
 
-/* Return the client auth in the map using the service identity public key.
+/** Return the client auth in the map using the service identity public key.
  * Return NULL if it does not exist in the map. */
 static hs_client_service_authorization_t *
 find_client_auth(const ed25519_public_key_t *service_identity_pk)
@@ -1256,7 +1256,7 @@ hs_client_note_connection_attempt_succeeded(const edge_connection_t *conn)
   }
 }
 
-/* With the given encoded descriptor in desc_str and the service key in
+/** With the given encoded descriptor in desc_str and the service key in
  * service_identity_pk, decode the descriptor and set the desc pointer with a
  * newly allocated descriptor object.
  *
@@ -1315,7 +1315,7 @@ hs_client_decode_descriptor(const char *desc_str,
   return -1;
 }
 
-/* Return true iff there are at least one usable intro point in the service
+/** Return true iff there are at least one usable intro point in the service
  * descriptor desc. */
 int
 hs_client_any_intro_points_usable(const ed25519_public_key_t *service_pk,
@@ -1364,7 +1364,7 @@ hs_client_refetch_hsdesc(const ed25519_public_key_t *identity_pk)
   return status;
 }
 
-/* This is called when we are trying to attach an AP connection to these
+/** This is called when we are trying to attach an AP connection to these
  * hidden service circuits from connection_ap_handshake_attach_circuit().
  * Return 0 on success, -1 for a transient error that is actions were
  * triggered to recover or -2 for a permenent error where both circuits will
@@ -1380,7 +1380,7 @@ hs_client_send_introduce1(origin_circuit_t *intro_circ,
                                                                 rend_circ);
 }
 
-/* Called when the client circuit circ has been established. It can be either
+/** Called when the client circuit circ has been established. It can be either
  * an introduction or rendezvous circuit. This function handles all hidden
  * service versions. */
 void
@@ -1410,7 +1410,7 @@ hs_client_circuit_has_opened(origin_circuit_t *circ)
   }
 }
 
-/* Called when we receive a RENDEZVOUS_ESTABLISHED cell. Change the state of
+/** Called when we receive a RENDEZVOUS_ESTABLISHED cell. Change the state of
  * the circuit to CIRCUIT_PURPOSE_C_REND_READY. Return 0 on success else a
  * negative value and the circuit marked for close. */
 int
@@ -1481,7 +1481,7 @@ client_service_authorization_free_all(void)
   digest256map_free(client_auths, client_service_authorization_free_void);
 }
 
-/* Check if the auth key file name is valid or not. Return 1 if valid,
+/** Check if the auth key file name is valid or not. Return 1 if valid,
  * otherwise return 0. */
 STATIC int
 auth_key_filename_is_valid(const char *filename)
@@ -1566,7 +1566,7 @@ parse_auth_file_content(const char *client_key_str)
   return auth;
 }
 
-/* From a set of <b>options</b>, setup every client authorization detail
+/** From a set of <b>options</b>, setup every client authorization detail
  * 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 configuration. */
@@ -1681,7 +1681,7 @@ hs_config_client_authorization(const or_options_t *options,
   return ret;
 }
 
-/* This is called when a descriptor has arrived following a fetch request and
+/** This is called when a descriptor has arrived following a fetch request and
  * has been stored in the client cache. Every entry connection that matches
  * the service identity key in the ident will get attached to the hidden
  * service circuit. */
@@ -1739,7 +1739,7 @@ hs_client_desc_has_arrived(const hs_ident_dir_conn_t *ident)
   smartlist_free(conns);
 }
 
-/* Return a newly allocated extend_info_t for a randomly chosen introduction
+/** Return a newly allocated extend_info_t for a randomly chosen introduction
  * point for the given edge connection identifier ident. Return NULL if we
  * can't pick any usable introduction points. */
 extend_info_t *
@@ -1752,7 +1752,7 @@ hs_client_get_random_intro_from_edge(const edge_connection_t *edge_conn)
     rend_client_get_random_intro(edge_conn->rend_data);
 }
 
-/* Called when get an INTRODUCE_ACK cell on the introduction circuit circ.
+/** Called when get an INTRODUCE_ACK cell on the introduction circuit circ.
  * Return 0 on success else a negative value is returned. The circuit will be
  * closed or reuse to extend again to another intro point. */
 int
@@ -1781,7 +1781,7 @@ hs_client_receive_introduce_ack(origin_circuit_t *circ,
   return ret;
 }
 
-/* Called when get a RENDEZVOUS2 cell on the rendezvous circuit circ.  Return
+/** Called when get a RENDEZVOUS2 cell on the rendezvous circuit circ.  Return
  * 0 on success else a negative value is returned. The circuit will be closed
  * on error. */
 int
@@ -1814,7 +1814,7 @@ hs_client_receive_rendezvous2(origin_circuit_t *circ,
   return ret;
 }
 
-/* Extend the introduction circuit circ to another valid introduction point
+/** Extend the introduction circuit circ to another valid introduction point
  * for the hidden service it is trying to connect to, or mark it and launch a
  * new circuit if we can't extend it.  Return 0 on success or possible
  * success. Return -1 and mark the introduction circuit for close on permanent
@@ -1864,7 +1864,7 @@ hs_client_reextend_intro_circuit(origin_circuit_t *circ)
   return ret;
 }
 
-/* Close all client introduction circuits related to the given descriptor.
+/** Close all client introduction circuits related to the given descriptor.
  * This is called with a descriptor that is about to get replaced in the
  * client cache.
  *
@@ -1896,7 +1896,7 @@ hs_client_close_intro_circuits_from_desc(const hs_descriptor_t *desc)
   }
 }
 
-/* Release all the storage held by the client subsystem. */
+/** Release all the storage held by the client subsystem. */
 void
 hs_client_free_all(void)
 {
@@ -1905,7 +1905,7 @@ hs_client_free_all(void)
   client_service_authorization_free_all();
 }
 
-/* Purge all potentially remotely-detectable state held in the hidden
+/** Purge all potentially remotely-detectable state held in the hidden
  * service client code. Called on SIGNAL NEWNYM. */
 void
 hs_client_purge_state(void)
@@ -1926,7 +1926,7 @@ hs_client_purge_state(void)
   log_info(LD_REND, "Hidden service client state has been purged.");
 }
 
-/* Called when our directory information has changed. */
+/** Called when our directory information has changed. */
 void
 hs_client_dir_info_changed(void)
 {

src/feature/hs/hs_client.h

@@ -13,31 +13,31 @@
 #include "feature/hs/hs_descriptor.h"
 #include "feature/hs/hs_ident.h"
 
-/* Status code of a descriptor fetch request. */
+/** Status code of a descriptor fetch request. */
 typedef enum {
-  /* Something internally went wrong. */
+  /** Something internally went wrong. */
   HS_CLIENT_FETCH_ERROR        = -1,
-  /* The fetch request has been launched successfully. */
+  /** The fetch request has been launched successfully. */
   HS_CLIENT_FETCH_LAUNCHED     = 0,
-  /* We already have a usable descriptor. No fetch. */
+  /** We already have a usable descriptor. No fetch. */
   HS_CLIENT_FETCH_HAVE_DESC    = 1,
-  /* No more HSDir available to query. */
+  /** No more HSDir available to query. */
   HS_CLIENT_FETCH_NO_HSDIRS    = 2,
-  /* The fetch request is not allowed. */
+  /** The fetch request is not allowed. */
   HS_CLIENT_FETCH_NOT_ALLOWED  = 3,
-  /* We are missing information to be able to launch a request. */
+  /** We are missing information to be able to launch a request. */
   HS_CLIENT_FETCH_MISSING_INFO = 4,
-  /* There is a pending fetch for the requested service. */
+  /** There is a pending fetch for the requested service. */
   HS_CLIENT_FETCH_PENDING      = 5,
 } hs_client_fetch_status_t;
 
 /** Client-side configuration of authorization for a service. */
 typedef struct hs_client_service_authorization_t {
-  /* An curve25519 secret key used to compute decryption keys that
+  /** An curve25519 secret key used to compute decryption keys that
    * allow the client to decrypt the hidden service descriptor. */
   curve25519_secret_key_t enc_seckey;
 
-  /* An onion address that is used to connect to the onion service. */
+  /** An onion address that is used to connect to the onion service. */
   char onion_address[HS_SERVICE_ADDR_LEN_BASE32+1];
 } hs_client_service_authorization_t;
 
@@ -120,4 +120,3 @@ STATIC digest256map_t *get_hs_client_auths_map(void);
 #endif /* defined(HS_CLIENT_PRIVATE) */
 
 #endif /* !defined(TOR_HS_CLIENT_H) */
-