Tempoary: Patches for javadoc thread

[fishtoprecords]

attached is patchfile updated copy of EventQueue.java with additional javadocs.

Same file is available on my website
http://pfarrell.com/java/EventQueue.java
and
http://pfarrell.com/java/EventQueue.diff


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 = 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;

[endolf]

Hi

These comments were verbose, but I've updated the javadoc on the event queue.

Endolf

[fishtoprecords]

Huh? Lots of the JDK code has fragments in the class showing how to use it.

1   2   3   4   5

/**      * test if queue is full. Note: package protected, not public       * @return true if the queue is full       */     final synchronized boolean isFull() {

One could argue about the need to point out its package protected, but the rest is minimal.

for

1   2   3   4   5   6

/**             * 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)

I assume that someone would know the answer to the question, and what a fixed size queue does when its full is a critical part of understanding the API.



The words on how the  getNextEvent(Event event) works are specifically to explain how it works, since it is so different from how "get()" works for the standard JDK's Queue functions.

More importantly, what is the downside of well strructured javadocs? The are removed in compilation, they only help programmers understand what the API does.

Games published by our own members! Check 'em out!

[Nate]

1   2   3   4   5

/**      * test if queue is full. Note: package protected, not public       * @return true if the queue is full       */     final synchronized boolean isFull() {

One could argue about the need to point out its package protected, but the rest is minimal.

I would say no javadocs should be on this method. You aren't providing anything that isn't already there in the method signature and method name. Noise != documentation.

1   2   3   4   5   6

/**             * 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)

I assume that someone would know the answer to the question, and what a fixed size queue does when its full is a critical part of understanding the API.

Again, none of this javadoc is useful. Also, javadocs should never contain questions! Either figure it out or ask someone else.

[endolf]

Those two methods are also internal to the API and not for use by users of the API, which is what I wrote instead

Endolf

[fishtoprecords]

Also, javadocs should never contain questions! Either figure it out or ask someone else.

I was assuming that whoever was doing the commit would either know the answer or remove the question. So rather than having a separate thread on the detail, I just put the question in the code

It was not clear from looking at the java code what the answer was.