Added a bit of documentation to the EventDispatcher.

git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@15229 a95241bf-73f2-0310-859d-f6bbb57e9c96

src/servers/app/Desktop.cpp

@@ -157,6 +157,7 @@ KeyboardFilter::Filter(BMessage* message, EventTarget** _target,
 	//	triggered yourself (like a pop-up window in your browser while
 	//	you're typing a password in another window) - maybe this should
 	//	be done differently, though (using something like B_LOCK_WINDOW_FOCUS)
+	//	(at least B_WINDOW_ACTIVATED must be postponed)
 
 	if (focus != fLastFocus && now - fTimestamp > 100000) {
 		// if the time span between the key presses is very short

src/servers/app/EventDispatcher.cpp

@@ -32,11 +32,26 @@
 
 
 /*!
-	The differentiation between messenger and token looks odd, but it
-	really has a reason as well:
+	The EventDispatcher is a per Desktop object that handles all input
+	events for that desktop.
+
+	The events are processed as needed in the Desktop class (via EventFilters),
+	and then forwarded to the actual target of the event, a client window
+	(or more correctly, to its EventTarget).
+	You cannot set the target of an event directly - the event filters need
+	to specify the targets.
+	The event loop will make sure that every target and interested listener
+	will get the event - it also delivers mouse moved events to the previous
+	target once so that this target can then spread the B_EXITED_VIEW transit
+	to the local target handler (usually a BView).
+
+	If you look at the event_listener structure below, the differentiation
+	between target and token may look odd, but it really has a reason as
+	well:
 	All events are sent to the preferred window handler only - the window
 	may then use the token or token list to identify the specific target
-	view(s).
+	view(s). This makes it possible to send every event only once, no
+	matter how many local target handlers there are.
 */
 
 struct event_listener {