Add comments to QueueEvent() and ConnectionEvent()

And also their "Fast" variants.

src/Event.h

@@ -58,6 +58,14 @@ public:
 	EventMgr();
 	~EventMgr() override;
 
+	// Queues an event without first checking if there's any available event
+	// handlers (or remote consumers).  If it turns out there's actually
+	// nothing that will consume the event, then this may leak memory due to
+	// failing to decrement the reference count of each element in 'vl'.  i.e.
+	// use this function instead of QueueEvent() if you've already guarded
+	// against the case where there's no handlers (one usually also does that
+	// because it would be a waste of effort to construct all the event
+	// arguments when there's no handlers to consume them).
 	void QueueEventFast(const EventHandlerPtr &h, val_list vl,
 			SourceID src = SOURCE_LOCAL, analyzer::ID aid = 0,
 			TimerMgr* mgr = 0, BroObj* obj = 0)
@@ -65,6 +73,12 @@ public:
 		QueueEvent(new Event(h, std::move(vl), src, aid, mgr, obj));
 		}
 
+	// Queues an event if there's an event handler (or remote consumer).  This
+	// function always takes ownership of decrementing the reference count of
+	// each element of 'vl', even if there's no event handler.  If you've
+	// checked for event handler existence, you may wish to call
+	// QueueEventFast() instead of this function to prevent the redundant
+	// existence check.
 	void QueueEvent(const EventHandlerPtr &h, val_list vl,
 			SourceID src = SOURCE_LOCAL, analyzer::ID aid = 0,
 			TimerMgr* mgr = 0, BroObj* obj = 0)
@@ -78,6 +92,10 @@ public:
 			}
 		}
 
+	// Same as QueueEvent, except taking the event's argument list via a
+	// pointer instead of by value.  This function takes ownership of the
+	// memory pointed to by 'vl' as well as decrementing the reference count of
+	// each of its elements.
 	void QueueEvent(const EventHandlerPtr &h, val_list* vl,
 			SourceID src = SOURCE_LOCAL, analyzer::ID aid = 0,
 			TimerMgr* mgr = 0, BroObj* obj = 0)