Turn circuitmux.c comments into module docs.

1 files changed, 47 insertions, 42 deletions

diff --git a/src/or/circuitmux.c b/src/or/circuitmux.c
index 038904e68a..96a3647aab 100644
--- a/src/or/circuitmux.c
+++ b/src/or/circuitmux.c
@@ -4,49 +4,20 @@
 /**
  * \file circuitmux.c
  * \brief Circuit mux/cell selection abstraction
- **/
-
-#include "or.h"
-#include "channel.h"
-#include "circuitlist.h"
-#include "circuitmux.h"
-#include "relay.h"
-
-/*
- * Private typedefs for circuitmux.c
- */
-
-/*
- * Map of muxinfos for circuitmux_t to use; struct is defined below (name
- * of struct must match HT_HEAD line).
- */
-typedef struct chanid_circid_muxinfo_map chanid_circid_muxinfo_map_t;
-
-/*
- * Hash table entry (yeah, calling it chanid_circid_muxinfo_s seems to
- * break the hash table code).
- */
-typedef struct chanid_circid_muxinfo_t chanid_circid_muxinfo_t;
-
-/*
- * Anything the mux wants to store per-circuit in the map; right now just
- * a count of queued cells.
- */
-
-typedef struct circuit_muxinfo_s circuit_muxinfo_t;
-
-/*
- * Structures for circuitmux.c
- */
-
-/*
- * A circuitmux is a collection of circuits; it tracks which subset
- * of the attached circuits are 'active' (i.e., have cells available
- * to transmit) and how many cells on each.  It expoes three distinct
+ *
+ * A circuitmux is responsible for <b>MU</b>ltiple<b>X</b>ing all of the
+ * circuits that are writing on a single channel. It keeps track of which of
+ * these circuits has something to write (aka, "active" circuits), and which
+ * one should write next.  A circuitmux corresponds 1:1 with a channel.
+ *
+ * There can be different implementations of the circuitmux's rules (which
+ * decide which circuit is next to write).
+ *
+ * A circuitmux exposes three distinct
  * interfaces to other components:
  *
  * To channels, which each have a circuitmux_t, the supported operations
- * are:
+ * (invoked from relay.c) are:
  *
  *   circuitmux_get_first_active_circuit():
  *
@@ -74,7 +45,9 @@ typedef struct circuit_muxinfo_s circuit_muxinfo_t;
  *
  *   circuitmux_set_num_cells():
  *
- *     Set the circuitmux's cell counter for this circuit.
+ *     Set the circuitmux's cell counter for this circuit. One of
+ *     circuitmuc_clear_num_cells() or circuitmux_set_num_cells() MUST be
+ *     called when the number of cells queued on a circuit changes.
  *
  * See circuitmux.h for the circuitmux_policy_t data structure, which contains
  * a table of function pointers implementing a circuit selection policy, and
@@ -94,7 +67,39 @@ typedef struct circuit_muxinfo_s circuit_muxinfo_t;
  *
  *     Install a policy on a circuitmux_t; the appropriate callbacks will be
  *     made to attach all existing circuits to the new policy.
- *
+ **/
+
+#include "or.h"
+#include "channel.h"
+#include "circuitlist.h"
+#include "circuitmux.h"
+#include "relay.h"
+
+/*
+ * Private typedefs for circuitmux.c
+ */
+
+/*
+ * Map of muxinfos for circuitmux_t to use; struct is defined below (name
+ * of struct must match HT_HEAD line).
+ */
+typedef struct chanid_circid_muxinfo_map chanid_circid_muxinfo_map_t;
+
+/*
+ * Hash table entry (yeah, calling it chanid_circid_muxinfo_s seems to
+ * break the hash table code).
+ */
+typedef struct chanid_circid_muxinfo_t chanid_circid_muxinfo_t;
+
+/*
+ * Anything the mux wants to store per-circuit in the map; right now just
+ * a count of queued cells.
+ */
+
+typedef struct circuit_muxinfo_s circuit_muxinfo_t;
+
+/*
+ * Structures for circuitmux.c
  */
 
 struct circuitmux_s {