Java-Gaming.org    
Featured games (81)
games approved by the League of Dukes
Games in Showcase (498)
Games in Android Showcase (117)
games submitted by our members
Games in WIP (564)
games currently in development
News: Read the Java Gaming Resources, or peek at the official Java tutorials
 
    Home     Help   Search   Login   Register   
Pages: [1]
  ignore  |  Print  
  Tempoary: Patches for javadoc thread  (Read 2679 times)
0 Members and 1 Guest are viewing this topic.
Offline fishtoprecords

Senior Newbie





« Posted 2011-02-05 16:03:29 »

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;
Offline endolf

JGO Coder


Medals: 7


Current project release date: sometime in 3003


« Reply #1 - Posted 2011-02-05 17:39:52 »

Hi

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

Endolf

Offline fishtoprecords

Senior Newbie





« Reply #2 - Posted 2011-02-05 20:05:44 »

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!
Legends of Yore - The Casual Retro Roguelike
Offline Nate

JGO Kernel


Medals: 147
Projects: 4
Exp: 14 years


Esoteric Software


« Reply #3 - Posted 2011-02-07 00:37:24 »

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.

Quote
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.

Offline endolf

JGO Coder


Medals: 7


Current project release date: sometime in 3003


« Reply #4 - Posted 2011-02-07 07:00:28 »

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

Endolf

Offline fishtoprecords

Senior Newbie





« Reply #5 - Posted 2011-02-08 23:53:08 »

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.
Pages: [1]
  ignore  |  Print  
 
 
You cannot reply to this message, because it is very, very old.

 

Add your game by posting it in the WIP section,
or publish it in Showcase.

The first screenshot will be displayed as a thumbnail.

Grunnt (21 views)
2014-09-23 14:38:19

radar3301 (14 views)
2014-09-21 23:33:17

BurntPizza (31 views)
2014-09-21 02:42:18

BurntPizza (22 views)
2014-09-21 01:30:30

moogie (20 views)
2014-09-21 00:26:15

UprightPath (29 views)
2014-09-20 20:14:06

BurntPizza (34 views)
2014-09-19 03:14:18

Dwinin (48 views)
2014-09-12 09:08:26

Norakomi (75 views)
2014-09-10 13:57:51

TehJavaDev (108 views)
2014-09-10 06:39:09
List of Learning Resources
by Longor1996
2014-08-16 10:40:00

List of Learning Resources
by SilverTiger
2014-08-05 19:33:27

Resources for WIP games
by CogWheelz
2014-08-01 16:20:17

Resources for WIP games
by CogWheelz
2014-08-01 16:19:50

List of Learning Resources
by SilverTiger
2014-07-31 16:29:50

List of Learning Resources
by SilverTiger
2014-07-31 16:26:06

List of Learning Resources
by SilverTiger
2014-07-31 11:54:12

HotSpot Options
by dleskov
2014-07-08 01:59:08
java-gaming.org is not responsible for the content posted by its members, including references to external websites, and other references that may or may not have a relation with our primarily gaming and game production oriented community. inquiries and complaints can be sent via email to the info‑account of the company managing the website of java‑gaming.org
Powered by MySQL Powered by PHP Powered by SMF 1.1.18 | SMF © 2013, Simple Machines | Managed by Enhanced Four Valid XHTML 1.0! Valid CSS!