Document the swiss-army-knife that retry_listeners has become

svn:r2584

diff --git a/src/or/connection.c b/src/or/connection.c
index f90b07f20e56f6c062037c52f5d3bf50b80f1ae7..0c45b7fb2bf8569be00d0b4add3db8ad87011e3a 100644 (file)
--- a/src/or/connection.c
+++ b/src/or/connection.c
@@ -552,6 +552,17 @@ static void listener_close_if_present(int type) {
   }
 }
 
+/** 
+ * Launch any configured listener connections of type <b>type</b>.  (A
+ * listener is configured if <b>port_option</b> is non-zero.  If any
+ * BindAddress configuration options are given in <b>cfg</b>, create a
+ * connection binding to each one.  Otherwise, create a single
+ * connection binding to the address <b>default_addr</b>.)
+ *
+ * If <b>force</b> is true, close and re-open all listener connections.
+ * Otherwise, only relaunch the listeners of this type if the number of 
+ * existing connections is not as configured (e.g., because one died).
+ */
 static int retry_listeners(int type, struct config_line_t *cfg,
                            int port_option, const char *default_addr,
                            int force)