Improve circpad documentation.

Patch by Tobias Pulls.

1 files changed, 11 insertions, 10 deletions

diff --git a/src/core/or/circuitpadding.h b/src/core/or/circuitpadding.h
index 3cf40e11db..fc2e595c0a 100644
--- a/src/core/or/circuitpadding.h
+++ b/src/core/or/circuitpadding.h
@@ -51,7 +51,7 @@ typedef enum {
   CIRCPAD_EVENT_INFINITY = 4,
   /* All histogram bins are empty (we are out of tokens) */
   CIRCPAD_EVENT_BINS_EMPTY = 5,
-  /* just a counter of the events above */
+  /* This state has used up its cell count */
   CIRCPAD_EVENT_LENGTH_COUNT = 6
 } circpad_event_t;
 #define CIRCPAD_NUM_EVENTS ((int)CIRCPAD_EVENT_LENGTH_COUNT+1)
@@ -79,7 +79,7 @@ typedef uint32_t circpad_delay_t;
  * An infinite padding cell delay means don't schedule any padding --
  * simply wait until a different event triggers a transition.
  *
- * This means that the maximum delay we can scedule is UINT32_MAX-1
+ * This means that the maximum delay we can schedule is UINT32_MAX-1
  * microseconds, or about 4300 seconds (1.25 hours).
  * XXX: Is this enough if we want to simulate light, intermittent
  * activity on an onion service?
@@ -106,8 +106,8 @@ typedef uint32_t circpad_delay_t;
  *
  * If any of these elements is set, then the circuit will be tested against
  * that specific condition. If an element is unset, then we don't test it.
- * (E.g. If neither NO_STREAMS or STREAMS are set, then we will not care
- * whether a circuit has streams attached when we apply a state machine)
+ * (E.g., if neither NO_STREAMS or STREAMS are set, then we will not care
+ * whether a circuit has streams attached when we apply a state machine.)
  *
  * The helper function circpad_circuit_state() converts circuit state
  * flags into this more compact representation.
@@ -255,8 +255,9 @@ typedef struct circpad_distribution_t {
 typedef uint16_t circpad_statenum_t;
 #define  CIRCPAD_STATENUM_MAX   (UINT16_MAX)
 
-/** A histogram is used to sample padding delays given a machine state.  This
- *  constant defines the maximum histogram width (i.e. the max number of bins).
+/** A histogram can be used to sample padding delays given a machine state.
+ * This constant defines the maximum histogram width (i.e. the max number of
+ * bins).
  *
  * The current limit is arbitrary and could be raised if there is a need,
  * however too many bins will be hard to serialize in the future.
@@ -275,10 +276,10 @@ typedef uint16_t circpad_statenum_t;
  * happen. The mutable information that gets updated in runtime are carried in
  * a circpad_machine_runtime_t.
  *
- * This struct describes the histograms and parameters of a single
- * state in the adaptive padding machine. Instances of this struct
- * exist in global circpad machine definitions that come from torrc
- * or the consensus.
+ * This struct describes the histograms and/or probability distributions, as
+ * well as parameters of a single state in the adaptive padding machine.
+ * Instances of this struct exist in global circpad machine definitions that
+ * come from torrc or the consensus.
  */
 typedef struct circpad_state_t {
   /**