Index: EventQueue.java
===================================================================
--- EventQueue.java	(revision 236)
+++ EventQueue.java	(working copy)
@@ -38,23 +38,56 @@
  *****************************************************************************/
 package net.java.games.input;
 
+   /**
+    * The <code>EventQueue</code> class implements a FIFO queue for Events.
+    * Typical usage pattern looks like:
+    * <pre>
+      for (Controller ctl : controllers) {
+            ctl.poll();
+            EventQueue localQueue = ctl.getEventQueue();
+            Event event = new Event();
+            while(localQueue.getNextEvent(event)) {
+                // do something cool here
+            }
+            try {
+                Thread.sleep(LOOP_TIME);
+            } catch (InterruptedException ex) {
+                // log exception
+            }
+        }
+    * </pre>
+    *
+    * @author Sun and open source contributors
+    */
 public final class EventQueue {
 	private final Event[] queue;
 	
 	private int head;
 	private int tail;
-
+           /**
+            * constructor, accepts argument with length of internal storage. Note, this constructor
+            * is not normally used by game developers, as they use the getEventQueue() function of
+            * Controller
+            * @param size capacity of the queue
+            */
 	public EventQueue(int size) {
 		queue = new Event[size + 1];
 		for (int i = 0; i < queue.length; i++)
 			queue[i] = new Event();
 	}
-
+           /**
+            * add one event to the queue.  Note: package protected, not public.
+            * Question: does this fail or block if queue is full?
+            * @param event the Event to add
+            */
 	final synchronized void add(Event event) {
 		queue[tail].set(event);
 		tail = increase(tail);
 	}
-
+           /**
+            * test if queue is full. Note: package protected, not public
+            * @return true if the queue is full
+            */
 	final synchronized boolean isFull() {
 		return increase(tail) == head;
 	}
@@ -62,7 +95,15 @@
 	private final int increase(int x) {
 		return (x + 1)%queue.length;
 	}
-
+           /**
+            * The getNextEvent method returns true if the queue <i>had</i> an event in it,
+            * and it managed to populate the event object you passed in with the details.
+            * False if there was nothing in the queue to copy in to your event object.
+            * Populating an object you pass in is an efficiency saving designed to reduce
+            * the number of objects created, and thus the amount of garbage collection needed.
+            * @param event
+            * @return  true if the queue <i>had</i> an event on it
+            */
 	public final synchronized boolean getNextEvent(Event event) {
 		if (head == tail)
 			return false;