Add comment explaining different channel close functions

diff --git a/src/or/channel.c b/src/or/channel.c
index 16dd9f903a900c8bb850de2cabcd981f6a04a55f..625d95781116de9fc033eb11bd7402ecc3ed35a6 100644 (file)
--- a/src/or/channel.c
+++ b/src/or/channel.c
@@ -1057,6 +1057,19 @@ channel_set_cell_handlers(channel_t *chan,
        chan->var_cell_handler)) channel_process_cells(chan);
 }
 
+/*
+ * On closing channels
+ *
+ * There are three functions that close channels, for use in
+ * different circumstances:
+ *
+ *  - Use channel_mark_for_close() for most cases
+ *  - Use channel_close_from_lower_layer() if you are connection_or.c
+ *    and the other end closes the underlying connection.
+ *  - Use channel_close_for_error() if you are connection_or.c and
+ *    some sort of error has occurred.
+ */
+
 /**
  * Mark a channel for closure
  *