remove blank line between function-comment and function

also be more consistent about punctuation in doxygen comments

src/or/channel.h

@@ -38,7 +38,6 @@ typedef enum {
  * to a particular node, and once constructed support the abstract operations
  * defined below.
  */
-
 struct channel_s {
   /** Magic number for type-checking cast macros */
   uint32_t magic;

src/or/channeltls.c

@@ -34,7 +34,6 @@
  * Define this so channel.h gives us things only channel_t subclasses
  * should touch.
  */
-
 #define TOR_CHANNEL_INTERNAL_
 
 #define CHANNELTLS_PRIVATE
@@ -132,7 +131,6 @@ static void channel_tls_process_padding_negotiate_cell(cell_t *cell,
  * Do parts of channel_tls_t initialization common to channel_tls_connect()
  * and channel_tls_handle_incoming().
  */
-
 STATIC void
 channel_tls_common_init(channel_tls_t *tlschan)
 {
@@ -168,13 +166,12 @@ channel_tls_common_init(channel_tls_t *tlschan)
 }
 
 /**
- * Start a new TLS channel
+ * Start a new TLS channel.
  *
  * Launch a new OR connection to <b>addr</b>:<b>port</b> and expect to
  * handshake with an OR with identity digest <b>id_digest</b>, and wrap
  * it in a channel_tls_t.
  */
-
 channel_t *
 channel_tls_connect(const tor_addr_t *addr, uint16_t port,
                     const char *id_digest,
@@ -233,12 +230,11 @@ channel_tls_connect(const tor_addr_t *addr, uint16_t port,
 }
 
 /**
- * Return the current channel_tls_t listener
+ * Return the current channel_tls_t listener.
  *
  * Returns the current channel listener for incoming TLS connections, or
  * NULL if none has been established
  */
-
 channel_listener_t *
 channel_tls_get_listener(void)
 {
@@ -246,12 +242,11 @@ channel_tls_get_listener(void)
 }
 
 /**
- * Start a channel_tls_t listener if necessary
+ * Start a channel_tls_t listener if necessary.
  *
  * Return the current channel_tls_t listener, or start one if we haven't yet,
  * and return that.
  */
-
 channel_listener_t *
 channel_tls_start_listener(void)
 {
@@ -278,12 +273,11 @@ channel_tls_start_listener(void)
 }
 
 /**
- * Free everything on shutdown
+ * Free everything on shutdown.
  *
  * Not much to do here, since channel_free_all() takes care of a lot, but let's
  * get rid of the listener.
  */
-
 void
 channel_tls_free_all(void)
 {
@@ -314,9 +308,8 @@ channel_tls_free_all(void)
 }
 
 /**
- * Create a new channel around an incoming or_connection_t
+ * Create a new channel around an incoming or_connection_t.
  */
-
 channel_t *
 channel_tls_handle_incoming(or_connection_t *orconn)
 {
@@ -359,7 +352,6 @@ channel_tls_handle_incoming(or_connection_t *orconn)
 /**
  * Cast a channel_tls_t to a channel_t.
  */
-
 channel_t *
 channel_tls_to_base(channel_tls_t *tlschan)
 {
@@ -372,7 +364,6 @@ channel_tls_to_base(channel_tls_t *tlschan)
  * Cast a channel_t to a channel_tls_t, with appropriate type-checking
  * asserts.
  */
-
 channel_tls_t *
 channel_tls_from_base(channel_t *chan)
 {
@@ -388,11 +379,10 @@ channel_tls_from_base(channel_t *chan)
  *******************************************/
 
 /**
- * Close a channel_tls_t
+ * Close a channel_tls_t.
  *
- * This implements the close method for channel_tls_t
+ * This implements the close method for channel_tls_t.
  */
-
 static void
 channel_tls_close_method(channel_t *chan)
 {
@@ -411,12 +401,11 @@ channel_tls_close_method(channel_t *chan)
 }
 
 /**
- * Describe the transport for a channel_tls_t
+ * Describe the transport for a channel_tls_t.
  *
  * This returns the string "TLS channel on connection <id>" to the upper
  * layer.
  */
-
 static const char *
 channel_tls_describe_transport_method(channel_t *chan)
 {
@@ -446,7 +435,7 @@ channel_tls_describe_transport_method(channel_t *chan)
 }
 
 /**
- * Free a channel_tls_t
+ * Free a channel_tls_t.
  *
  * This is called by the generic channel layer when freeing a channel_tls_t;
  * this happens either on a channel which has already reached
@@ -455,7 +444,6 @@ channel_tls_describe_transport_method(channel_t *chan)
  * have an orconn active (which connection_free_all() will get to later),
  * so we should null out its channel pointer now.
  */
-
 static void
 channel_tls_free_method(channel_t *chan)
 {
@@ -470,9 +458,8 @@ channel_tls_free_method(channel_t *chan)
 }
 
 /**
- * Get an estimate of the average TLS overhead for the upper layer
+ * Get an estimate of the average TLS overhead for the upper layer.
  */
-
 static double
 channel_tls_get_overhead_estimate_method(channel_t *chan)
 {
@@ -505,13 +492,12 @@ channel_tls_get_overhead_estimate_method(channel_t *chan)
 }
 
 /**
- * Get the remote address of a channel_tls_t
+ * Get the remote address of a channel_tls_t.
  *
  * This implements the get_remote_addr method for channel_tls_t; copy the
  * remote endpoint of the channel to addr_out and return 1 (always
  * succeeds for this transport).
  */
-
 static int
 channel_tls_get_remote_addr_method(channel_t *chan, tor_addr_t *addr_out)
 {
@@ -535,8 +521,8 @@ channel_tls_get_remote_addr_method(channel_t *chan, tor_addr_t *addr_out)
  * This implements the get_transport_name for channel_tls_t. If the
  * channel uses a pluggable transport, copy its name to
  * <b>transport_out</b> and return 0. If the channel did not use a
- * pluggable transport, return -1. */
-
+ * pluggable transport, return -1.
+ */
 static int
 channel_tls_get_transport_name_method(channel_t *chan, char **transport_out)
 {
@@ -554,14 +540,13 @@ channel_tls_get_transport_name_method(channel_t *chan, char **transport_out)
 }
 
 /**
- * Get endpoint description of a channel_tls_t
+ * Get endpoint description of a channel_tls_t.
  *
  * This implements the get_remote_descr method for channel_tls_t; it returns
  * a text description of the remote endpoint of the channel suitable for use
- * in log messages.  The req parameter is 0 for the canonical address or 1 for
+ * in log messages. The req parameter is 0 for the canonical address or 1 for
  * the actual address seen.
  */
-
 static const char *
 channel_tls_get_remote_descr_method(channel_t *chan, int flags)
 {
@@ -617,12 +602,11 @@ channel_tls_get_remote_descr_method(channel_t *chan, int flags)
 }
 
 /**
- * Tell the upper layer if we have queued writes
+ * Tell the upper layer if we have queued writes.
  *
  * This implements the has_queued_writes method for channel_tls t_; it returns
  * 1 iff we have queued writes on the outbuf of the underlying or_connection_t.
  */
-
 static int
 channel_tls_has_queued_writes_method(channel_t *chan)
 {
@@ -645,13 +629,12 @@ channel_tls_has_queued_writes_method(channel_t *chan)
 }
 
 /**
- * Tell the upper layer if we're canonical
+ * Tell the upper layer if we're canonical.
  *
  * This implements the is_canonical method for channel_tls_t; if req is zero,
  * it returns whether this is a canonical channel, and if it is one it returns
  * whether that can be relied upon.
  */
-
 static int
 channel_tls_is_canonical_method(channel_t *chan, int req)
 {
@@ -684,12 +667,11 @@ channel_tls_is_canonical_method(channel_t *chan, int req)
 }
 
 /**
- * Check if we match an extend_info_t
+ * Check if we match an extend_info_t.
  *
  * This implements the matches_extend_info method for channel_tls_t; the upper
  * layer wants to know if this channel matches an extend_info_t.
  */
-
 static int
 channel_tls_matches_extend_info_method(channel_t *chan,
                                        extend_info_t *extend_info)
@@ -720,7 +702,6 @@ channel_tls_matches_extend_info_method(channel_t *chan,
  * layer wants to know if this channel matches a target address when extending
  * a circuit.
  */
-
 static int
 channel_tls_matches_target_method(channel_t *chan,
                                   const tor_addr_t *target)
@@ -755,7 +736,6 @@ channel_tls_matches_target_method(channel_t *chan,
  * Tell the upper layer how many bytes we have queued and not yet
  * sent.
  */
-
 static size_t
 channel_tls_num_bytes_queued_method(channel_t *chan)
 {
@@ -768,13 +748,12 @@ channel_tls_num_bytes_queued_method(channel_t *chan)
 }
 
 /**
- * Tell the upper layer how many cells we can accept to write
+ * Tell the upper layer how many cells we can accept to write.
  *
  * This implements the num_cells_writeable method for channel_tls_t; it
  * returns an estimate of the number of cells we can accept with
  * channel_tls_write_*_cell().
  */
-
 static int
 channel_tls_num_cells_writeable_method(channel_t *chan)
 {
@@ -799,12 +778,11 @@ channel_tls_num_cells_writeable_method(channel_t *chan)
 }
 
 /**
- * Write a cell to a channel_tls_t
+ * Write a cell to a channel_tls_t.
  *
  * This implements the write_cell method for channel_tls_t; given a
  * channel_tls_t and a cell_t, transmit the cell_t.
  */
-
 static int
 channel_tls_write_cell_method(channel_t *chan, cell_t *cell)
 {
@@ -828,7 +806,7 @@ channel_tls_write_cell_method(channel_t *chan, cell_t *cell)
 }
 
 /**
- * Write a packed cell to a channel_tls_t
+ * Write a packed cell to a channel_tls_t.
  *
  * This implements the write_packed_cell method for channel_tls_t; given a
  * channel_tls_t and a packed_cell_t, transmit the packed_cell_t.
@@ -836,7 +814,6 @@ channel_tls_write_cell_method(channel_t *chan, cell_t *cell)
  * Return 0 on success or negative value on error. The caller must free the
  * packed cell.
  */
-
 static int
 channel_tls_write_packed_cell_method(channel_t *chan,
                                      packed_cell_t *packed_cell)
@@ -863,12 +840,11 @@ channel_tls_write_packed_cell_method(channel_t *chan,
 }
 
 /**
- * Write a variable-length cell to a channel_tls_t
+ * Write a variable-length cell to a channel_tls_t.
  *
  * This implements the write_var_cell method for channel_tls_t; given a
  * channel_tls_t and a var_cell_t, transmit the var_cell_t.
  */
-
 static int
 channel_tls_write_var_cell_method(channel_t *chan, var_cell_t *var_cell)
 {
@@ -896,11 +872,10 @@ channel_tls_write_var_cell_method(channel_t *chan, var_cell_t *var_cell)
  ************************************************/
 
 /**
- * Close a channel_listener_t
+ * Close a channel_listener_t.
  *
- * This implements the close method for channel_listener_t
+ * This implements the close method for channel_listener_t.
  */
-
 static void
 channel_tls_listener_close_method(channel_listener_t *chan_l)
 {
@@ -936,12 +911,11 @@ channel_tls_listener_close_method(channel_listener_t *chan_l)
 }
 
 /**
- * Describe the transport for a channel_listener_t
+ * Describe the transport for a channel_listener_t.
  *
  * This returns the string "TLS channel (listening)" to the upper
  * layer.
  */
-
 static const char *
 channel_tls_listener_describe_transport_method(channel_listener_t *chan_l)
 {
@@ -955,12 +929,11 @@ channel_tls_listener_describe_transport_method(channel_listener_t *chan_l)
  ******************************************************/
 
 /**
- * Handle an orconn state change
+ * Handle an orconn state change.
  *
  * This function will be called by connection_or.c when the or_connection_t
  * associated with this channel_tls_t changes state.
  */
-
 void
 channel_tls_handle_state_change_on_orconn(channel_tls_t *chan,
                                           or_connection_t *conn,
@@ -1011,13 +984,12 @@ channel_tls_handle_state_change_on_orconn(channel_tls_t *chan,
 #ifdef KEEP_TIMING_STATS
 
 /**
- * Timing states wrapper
+ * Timing states wrapper.
  *
  * This is a wrapper function around the actual function that processes the
  * <b>cell</b> that just arrived on <b>chan</b>. Increment <b>*time</b>
  * by the number of microseconds used by the call to <b>*func(cell, chan)</b>.
  */
-
 static void
 channel_tls_time_process_cell(cell_t *cell, channel_tls_t *chan, int *time,
                               void (*func)(cell_t *, channel_tls_t *))
@@ -1046,7 +1018,7 @@ channel_tls_time_process_cell(cell_t *cell, channel_tls_t *chan, int *time,
 #endif /* defined(KEEP_TIMING_STATS) */
 
 /**
- * Handle an incoming cell on a channel_tls_t
+ * Handle an incoming cell on a channel_tls_t.
  *
  * This is called from connection_or.c to handle an arriving cell; it checks
  * for cell types specific to the handshake for this transport protocol and
@@ -1058,7 +1030,6 @@ channel_tls_time_process_cell(cell_t *cell, channel_tls_t *chan, int *time,
  * for copying in the case that it queues; we merely pass pointers through
  * which we get from connection_or_process_cells_from_inbuf().
  */
-
 void
 channel_tls_handle_cell(cell_t *cell, or_connection_t *conn)
 {
@@ -1160,7 +1131,7 @@ channel_tls_handle_cell(cell_t *cell, or_connection_t *conn)
 }
 
 /**
- * Handle an incoming variable-length cell on a channel_tls_t
+ * Handle an incoming variable-length cell on a channel_tls_t.
  *
  * Process a <b>var_cell</b> that was just received on <b>conn</b>. Keep
  * internal statistics about how many of each cell we've processed so far
@@ -1176,7 +1147,6 @@ channel_tls_handle_cell(cell_t *cell, or_connection_t *conn)
  * caller always frees them after this function returns, so this function
  * should never free var_cell.
  */
-
 void
 channel_tls_handle_var_cell(var_cell_t *var_cell, or_connection_t *conn)
 {
@@ -1341,7 +1311,7 @@ channel_tls_handle_var_cell(var_cell_t *var_cell, or_connection_t *conn)
 }
 
 /**
- * Update channel marks after connection_or.c has changed an address
+ * Update channel marks after connection_or.c has changed an address.
  *
  * This is called from connection_or_init_conn_from_address() after the
  * connection's _base.addr or real_addr fields have potentially been changed
@@ -1350,7 +1320,6 @@ channel_tls_handle_var_cell(var_cell_t *var_cell, or_connection_t *conn)
  * remote router by looking it up in the consensus after we finish the
  * handshake and know an authenticated identity digest.
  */
-
 void
 channel_tls_update_marks(or_connection_t *conn)
 {
@@ -1379,12 +1348,11 @@ channel_tls_update_marks(or_connection_t *conn)
 }
 
 /**
- * Check if this cell type is allowed before the handshake is finished
+ * Check if this cell type is allowed before the handshake is finished.
  *
  * Return true if <b>command</b> is a cell command that's allowed to start a
  * V3 handshake.
  */
-
 static int
 command_allowed_before_handshake(uint8_t command)
 {
@@ -1399,14 +1367,13 @@ command_allowed_before_handshake(uint8_t command)
 }
 
 /**
- * Start a V3 handshake on an incoming connection
+ * Start a V3 handshake on an incoming connection.
  *
  * Called when we as a server receive an appropriate cell while waiting
  * either for a cell or a TLS handshake.  Set the connection's state to
  * "handshaking_v3', initializes the or_handshake_state field as needed,
  * and add the cell to the hash of incoming cells.)
  */
-
 static int
 enter_v3_handshake_with_cell(var_cell_t *cell, channel_tls_t *chan)
 {
@@ -1447,7 +1414,6 @@ enter_v3_handshake_with_cell(var_cell_t *cell, channel_tls_t *chan)
  * we support, pick the highest version we have in common, and continue the
  * negotiation from there.
  */
-
 static void
 channel_tls_process_versions_cell(var_cell_t *cell, channel_tls_t *chan)
 {
@@ -1622,7 +1588,7 @@ channel_tls_process_versions_cell(var_cell_t *cell, channel_tls_t *chan)
 }
 
 /**
- * Process a 'padding_negotiate' cell
+ * Process a 'padding_negotiate' cell.
  *
  * This function is called to handle an incoming PADDING_NEGOTIATE cell;
  * enable or disable padding accordingly, and read and act on its timeout
@@ -1659,12 +1625,11 @@ channel_tls_process_padding_negotiate_cell(cell_t *cell, channel_tls_t *chan)
 }
 
 /**
- * Process a 'netinfo' cell
+ * Process a 'netinfo' cell.
  *
  * This function is called to handle an incoming NETINFO cell; read and act
  * on its contents, and set the connection state to "open".
  */
-
 static void
 channel_tls_process_netinfo_cell(cell_t *cell, channel_tls_t *chan)
 {
@@ -2167,7 +2132,7 @@ channel_tls_process_certs_cell(var_cell_t *cell, channel_tls_t *chan)
 }
 
 /**
- * Process an AUTH_CHALLENGE cell from a channel_tls_t
+ * Process an AUTH_CHALLENGE cell from a channel_tls_t.
  *
  * This function is called to handle an incoming AUTH_CHALLENGE cell on a
  * channel_tls_t; if we weren't supposed to get one (for example, because we're
@@ -2176,7 +2141,6 @@ channel_tls_process_certs_cell(var_cell_t *cell, channel_tls_t *chan)
  * want to authenticate, just drop it.  If the cell is well-formed *and* we
  * want to authenticate, send an AUTHENTICATE cell and then a NETINFO cell.
  */
-
 STATIC void
 channel_tls_process_auth_challenge_cell(var_cell_t *cell, channel_tls_t *chan)
 {
@@ -2270,7 +2234,7 @@ channel_tls_process_auth_challenge_cell(var_cell_t *cell, channel_tls_t *chan)
 }
 
 /**
- * Process an AUTHENTICATE cell from a channel_tls_t
+ * Process an AUTHENTICATE cell from a channel_tls_t.
  *
  * If it's ill-formed or we weren't supposed to get one or we're not doing a
  * v3 handshake, then mark the connection.  If it does not authenticate the
@@ -2278,7 +2242,6 @@ channel_tls_process_auth_challenge_cell(var_cell_t *cell, channel_tls_t *chan)
  * we didn't get a CERTS cell, etc) mark the connection.  Otherwise, accept
  * the identity of the router on the other side of the connection.
  */
-
 STATIC void
 channel_tls_process_authenticate_cell(var_cell_t *cell, channel_tls_t *chan)
 {