From 903605ff58e7b75d6872a1ec14383971b128a876 Mon Sep 17 00:00:00 2001
From: Nick Hudson <nick.hudson@isode.com>
Date: Thu, 12 Jan 2012 16:42:26 +0000
Subject: Add some javadoc to Event.java

In trying to use the Event class I wasn't sure exactly what it was
doing so have added javadoc to try and make it clearer.

I also added "toString()" method to Event.java for debugging purposes.

Test-information:

"ant javadoc" works and info looks as expected.

Running in debugger now shows me info derived from "toString()" method
when I click on Event objects

diff --git a/src/com/isode/stroke/eventloop/Event.java b/src/com/isode/stroke/eventloop/Event.java
index c4784d6..4c236bf 100644
--- a/src/com/isode/stroke/eventloop/Event.java
+++ b/src/com/isode/stroke/eventloop/Event.java
@@ -4,15 +4,47 @@
  * See Documentation/Licenses/GPLv3.txt for more information.
  */
 /*
- * Copyright (c) 2010, Isode Limited, London, England.
+ * Copyright (c) 2010-2012, Isode Limited, London, England.
  * All rights reserved.
  */
 package com.isode.stroke.eventloop;
 
+/**
+ * An Event object represents an external event that requires processing. 
+ * A concrete {@link EventLoop} implementation must ensure that Events are 
+ * processed in the application's main event loop. 
+ * 
+ * <p>An application (and any concrete class of EventLoop) should treat Events
+ * as opaque objects to be passed to {@link EventLoop#handleEvent(Event)}.
+ *  
+ * <p>Event processing is designed to happen in the main event loop, so for
+ * example a GUI application might handle Events in the following manner:
+ * <pre>
+ *  EventLoop eventLoop = new EventLoop() {
+ *     protected void post(final Event event) {
+ *       // Invoke the callback in the AWT display thread     
+ *       SwingUtilities.invokeLater(new Runnable() {
+ *           public void run() {
+ *              handleEvent(event);
+ *          }
+ *       });
+ *     }
+ *  };
+ *  .
+ *  .
+ *  .
+ *  client.onConnected.connect(new Slot() {
+ *     public void call() {
+ *        // This will always be called inside the event dispatching thread
+ *        updateSomeTextFieldInTheGUI("Connected");
+ *     }
+ *  });
+ * </pre>
+ * 
+ */
 public class Event {
 
     public interface Callback {
-
         void run();
     }
 
@@ -39,4 +71,12 @@ public class Event {
     final int id;
     final EventOwner owner;
     public final Callback callback;
+    
+    @Override
+    public String toString() {
+        return "Event with id=" + id + 
+        " callback=" + callback +
+        (owner == null ? " (no owner information)" : " owner=" + owner);
+        
+    }
 }
-- 
cgit v0.10.2-6-g49f6