[tor-commits] [tor/master] circpad: Documentation improvements after Nick's review.

[nickm at torproject.org]

commit 32c821c47b56471802a6c6c0f2286eb41d07238b
Author: George Kadianakis <desnacked at riseup.net>
Date:   Tue Mar 12 18:38:55 2019 +0200

    circpad: Documentation improvements after Nick's review.
---
 src/core/or/circuitpadding.c | 10 ++++++----
 src/core/or/circuitpadding.h |  3 ++-
 2 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/src/core/or/circuitpadding.c b/src/core/or/circuitpadding.c
index b7e4b5684..106bb4ffa 100644
--- a/src/core/or/circuitpadding.c
+++ b/src/core/or/circuitpadding.c
@@ -222,8 +222,9 @@ circpad_machine_current_state(const circpad_machine_state_t *mi)
 }
 
 /**
- * Get the lower bound of a histogram bin. The upper bound is obtained by
- * calling this function with bin+1, and subtracting 1.
+ * Get the lower bound of a histogram bin.
+ *
+ * You can obtain the upper bound using histogram_get_bin_upper_bound().
  *
  * This function can also be called with 'bin' set to a value equal or greater
  * than histogram_len in which case the infinity bin is chosen and
@@ -273,8 +274,7 @@ circpad_get_histogram_bin_midpoint(const circpad_machine_state_t *mi,
                            int bin_index)
 {
   circpad_delay_t left_bound = circpad_histogram_bin_to_usec(mi, bin_index);
-  circpad_delay_t right_bound =
-    circpad_histogram_bin_to_usec(mi, bin_index+1)-1;
+  circpad_delay_t right_bound = histogram_get_bin_upper_bound(mi, bin_index);
 
   return left_bound + (right_bound - left_bound)/2;
 }
@@ -381,6 +381,8 @@ circpad_choose_state_length(circpad_machine_state_t *mi)
 /**
  * Sample a value from our iat_dist, and clamp it safely
  * to circpad_delay_t.
+ *
+ * Before returning, add <b>delay_shift</b> (can be zero) to the sampled value.
  */
 static circpad_delay_t
 circpad_distribution_sample_iat_delay(const circpad_state_t *state,
diff --git a/src/core/or/circuitpadding.h b/src/core/or/circuitpadding.h
index 74f9f35c9..2c763f46e 100644
--- a/src/core/or/circuitpadding.h
+++ b/src/core/or/circuitpadding.h
@@ -291,7 +291,8 @@ typedef struct circpad_state_t {
   /** The histogram itself: an array of uint16s of tokens, whose
    *  widths are exponentially spaced, in microseconds.
    *
-   *  This array must have histogram_len elements. */
+   *  This array must have histogram_len elements that are (non-strictly)
+   *  monotonically increasing. */
   circpad_hist_token_t histogram[CIRCPAD_MAX_HISTOGRAM_LEN];
   /* The histogram bin edges in usec.
    *