Revision: 704
Author: allain.lalonde
Date: Tue Oct 13 09:36:51 2009
Log: More CheckStyle blitzing on core. Javadocs are all there now. To drop  
the number much further I'll need to expand expressions for defining  
Property change codes, or break binary compatability by making constants  
final. I'm 100% for doing that, but I understand some people have  
reservations.
http://code.google.com/p/piccolo2d/source/detail?r=704

Modified:
  /piccolo2d.java/trunk/core/src/build/conf/checkstyle.xml
   
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/activities/PColorActivity.java
   
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/activities/PInterpolatingActivity.java
   
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/activities/PTransformActivity.java
   
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/event/PBasicInputEventHandler.java
   
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/nodes/PPath.java
   
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/nodes/PText.java
   
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PBounds.java
   
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PObjectOutputStream.java
   
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PPaintContext.java
   
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PPickPath.java
  /piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PUtil.java

=======================================
--- /piccolo2d.java/trunk/core/src/build/conf/checkstyle.xml    Thu Oct  8  
14:01:22 2009
+++ /piccolo2d.java/trunk/core/src/build/conf/checkstyle.xml    Tue Oct 13  
09:36:51 2009
@@ -151,7 +151,10 @@
          </module>
          <module name="IllegalInstantiation"/>
          <module name="InnerAssignment"/>
-        <module name="MagicNumber"/>
+        <!--  TODO: Make this check ints and longs aswell -->
+        <module name="MagicNumber">
+               <property name="ignoreNumbers" value="0, 0.5, 2, 1, -1, 1000" />
+        </module>
          <module name="MissingSwitchDefault"/>
          <module name="RedundantThrows"/>
          <module name="SimplifyBooleanExpression"/>
=======================================
---  
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/activities/PColorActivity.java
       
Mon Oct 12 18:58:11 2009
+++  
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/activities/PColorActivity.java
       
Tue Oct 13 09:36:51 2009
@@ -137,7 +137,7 @@
       * Set the final color that will be set on the color activities target  
when
       * the activity stops stepping.
       *
-     * @param newDestination  to animate towards
+     * @param newDestination to animate towards
       */
      public void setDestinationColor(final Color newDestination) {
          destination = newDestination;
@@ -166,6 +166,6 @@
          final float green = source.getGreen() + zeroToOne *  
(destination.getGreen() - source.getGreen());
          final float blue = source.getBlue() + zeroToOne *  
(destination.getBlue() - source.getBlue());
          final float alpha = source.getAlpha() + zeroToOne *  
(destination.getAlpha() - source.getAlpha());
-        target.setColor(new Color(red / 255, green / 255, blue / 255,  
alpha / 255));
+        target.setColor(new Color((int) red, (int) green, (int) blue,  
(int) alpha));
      }
  }
=======================================
---  
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/activities/PInterpolatingActivity.java
       
Mon Oct 12 18:58:11 2009
+++  
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/activities/PInterpolatingActivity.java
       
Tue Oct 13 09:36:51 2009
@@ -88,8 +88,9 @@
       * @param duration duration in milliseconds of the entire activity
       * @param stepRate interval in milliseconds between updates to target
       * @param loopCount # of times to repeat this activity.
-     * @param mode controls the direction of the interpolation (source to  
destination,
-     *            destination to source, or source to destination back to  
source)
+     * @param mode controls the direction of the interpolation (source to
+     *            destination, destination to source, or source to  
destination
+     *            back to source)
       */
      public PInterpolatingActivity(final long duration, final long  
stepRate, final int loopCount, final int mode) {
          this(duration, stepRate, System.currentTimeMillis(), loopCount,  
mode);
@@ -305,7 +306,7 @@
       * @return strength of acceleration
       */
      public float computeSlowInSlowOut(final float zeroToOne) {
-        if (zeroToOne < 0.5) {
+        if (zeroToOne < 0.5f) {
              return 2.0f * zeroToOne * zeroToOne;
          }
          else {
@@ -327,11 +328,11 @@
                  break;

              case SOURCE_TO_DESTINATION_TO_SOURCE:
-                if (zeroToOne <= 0.5) {
+                if (zeroToOne <= 0.5f) {
                      adjustedZeroToOne = zeroToOne * 2;
                  }
                  else {
-                    adjustedZeroToOne = 1 - (zeroToOne - 0.5f) * 2;
+                    adjustedZeroToOne = 2 * (1 - zeroToOne);
                  }
                  break;
              case SOURCE_TO_DESTINATION:
=======================================
---  
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/activities/PTransformActivity.java
   
Mon Oct 12 18:58:11 2009
+++  
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/activities/PTransformActivity.java
   
Tue Oct 13 09:36:51 2009
@@ -79,8 +79,8 @@
       * duration, will update at the given step rate and will be applied to  
the
       * target.
       *
-     * TODO: document what the destination transform is set to when not
-     * specified. (Looks like the Zero vector, but that can't be right,  
can it?)
+     * Requires that the developer follow up with a setDestinationTransform
+     * call, otherwise the transition is undefined.
       *
       * @param duration duration in milliseconds of the entire activity
       * @param stepRate interval in milliseconds between successive  
animation
=======================================
---  
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/event/PBasicInputEventHandler.java
   
Mon Oct 12 18:58:11 2009
+++  
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/event/PBasicInputEventHandler.java
   
Tue Oct 13 09:36:51 2009
@@ -276,12 +276,9 @@
       * This method is invoked when the mouse wheel is rotated by a block.
       * Subclasses should override this method to implement their own  
behavior.
       *
-     * TODO: check that this means 1 tick of the wheel.
-     *
       * @param event an object that can be queries to discover the event's
       *            details
       */
-
      public void mouseWheelRotatedByBlock(final PInputEvent event) {
      }

=======================================
---  
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/nodes/PPath.java    
 
Mon Oct 12 18:58:11 2009
+++  
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/nodes/PPath.java    
 
Tue Oct 13 09:36:51 2009
@@ -491,12 +491,15 @@
      }

      /**
-     * Appends a quad line to the end of the path.
+     * Adds a curved segment, defined by two new points, to the path by  
drawing
+     * a Quadratic curve that intersects both the current coordinates and  
the
+     * coordinates (x2, y2), using the specified point (x1, y1) as a  
quadratic
+     * parametric control point.
       *
-     * @param x1
-     * @param y1
-     * @param x2
-     * @param y2
+     * @param x1 x component of quadratic parametric control point
+     * @param y1 y component of quadratic parametric control point
+     * @param x2 x component of point through which quad curve will pass
+     * @param y2 y component of point through which quad curve will pass
       */
      public void quadTo(final float x1, final float y1, final float x2,  
final float y2) {
          path.quadTo(x1, y1, x2, y2);
@@ -506,14 +509,17 @@
      }

      /**
-     * Appends a curve to the end of the path.
+     * Adds a curved segment, defined by three new points, to the path by
+     * drawing a Bézier curve that intersects both the current coordinates  
and
+     * the coordinates (x3, y3), using the specified points (x1, y1) and  
(x2,
+     * y2) as Bézier control points.
       *
-     * @param x1
-     * @param y1
-     * @param x2
-     * @param y2
-     * @param x3
-     * @param y3
+     * @param x1 x component of first Bézier control point
+     * @param y1 y component of first Bézier control point
+     * @param x2 x component of second Bézier control point
+     * @param y2 y component of second Bézier control point
+     * @param x3 x component of point through which curve must pass
+     * @param y3 y component of point through which curve must pass
       */
      public void curveTo(final float x1, final float y1, final float x2,  
final float y2, final float x3, final float y3) {
          path.curveTo(x1, y1, x2, y2, x3, y3);
=======================================
---  
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/nodes/PText.java    
 
Fri Oct  9 08:29:14 2009
+++  
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/nodes/PText.java    
 
Tue Oct 13 09:36:51 2009
@@ -176,12 +176,20 @@
          setText(text);
      }

-    /** @deprecated by {...@link #getHorizontalAlignment()} */
+    /**
+     * @deprecated by {...@link #getHorizontalAlignment()}
+     *
+     * @return the horizontal alignment value of this node
+     */
      public float getJustification() {
          return getHorizontalAlignment();
      }

-    /** @deprecated by {...@link #setHorizontalAlignment(float)} */
+    /**
+     * @deprecated by {...@link #setHorizontalAlignment(float)}
+     *
+     * @param justification horizontal alignment value to assign to this  
node
+     */
      public void setJustification(final float justification) {
          setHorizontalAlignment(justification);
      }
@@ -359,7 +367,12 @@
          }

          final String oldText = text;
-        text = newText == null ? DEFAULT_TEXT : newText;
+        if (newText == null) {
+            text = DEFAULT_TEXT;
+        }
+        else {
+            text = newText;
+        }
          lines = null;
          recomputeLayout();
          invalidatePaint();
@@ -392,7 +405,13 @@
              return;
          }
          final Font oldFont = this.font;
-        this.font = font == null ? DEFAULT_FONT : font;
+        if (font == null) {
+            this.font = DEFAULT_FONT;
+        }
+        else {
+            this.font = font;
+        }
+
          lines = null;
          recomputeLayout();
          invalidatePaint();
@@ -413,7 +432,13 @@
              atString.addAttribute(TextAttribute.FONT, getFont());
              final AttributedCharacterIterator itr = atString.getIterator();
              final LineBreakMeasurer measurer = new LineBreakMeasurer(itr,  
PPaintContext.RENDER_QUALITY_HIGH_FRC);
-            final float availableWidth = constrainWidthToTextWidth ?  
Float.MAX_VALUE : (float) getWidth();
+            final float availableWidth;
+            if (constrainWidthToTextWidth) {
+                availableWidth = Float.MAX_VALUE;
+            }
+            else {
+                availableWidth = (float) getWidth();
+            }

              int nextLineBreakOffset = text.indexOf('\n');
              if (nextLineBreakOffset == -1) {
=======================================
---  
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PBounds.java   
 
Mon Oct 12 18:58:11 2009
+++  
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PBounds.java   
 
Tue Oct 13 09:36:51 2009
@@ -77,7 +77,7 @@
      }

      /**
-     * Creates a bounds with the same shape as the rectangle provided
+     * Creates a bounds with the same shape as the rectangle provided.
       *
       * @param aBounds rectangle to be copied
       */
@@ -100,7 +100,8 @@
      }

      /**
-     * Constructs a PBounds object at the given coordinates with the given  
dimensions.
+     * Constructs a PBounds object at the given coordinates with the given
+     * dimensions.
       *
       * @param x left of bounds
       * @param y top of bounds
@@ -114,8 +115,10 @@

      /**
       * Returns a clone of this node.
+     *
+     * @return cloned copy of this bounds
       */
-    public Object clone() {
+    public Object clone() {
          return new PBounds(this);
      }

@@ -241,10 +244,10 @@
              isEmpty = false;
          }
          else {
-            final double x1 = x <= bounds.x ? x : bounds.x;
-            final double y1 = y <= bounds.y ? y : bounds.y;
-            final double x2 = x + width >= bounds.x + bounds.width ? x +  
width : bounds.x + bounds.width;
-            final double y2 = y + height >= bounds.y + bounds.height ? y +  
height : bounds.y + bounds.height;
+            final double x1 = Math.min(x, bounds.x);
+            final double y1 = Math.min(y, bounds.y);
+            final double x2 = Math.max(x + width, bounds.x + bounds.width);
+            final double y2 = Math.max(y + height, bounds.y +  
bounds.height);

              x = x1;
              y = y1;
=======================================
---  
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PObjectOutputStream.java
        
Thu Oct  8 21:40:23 2009
+++  
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PObjectOutputStream.java
        
Tue Oct 13 09:36:51 2009
@@ -73,7 +73,7 @@
      /**
       * Transform the given object into an array of bytes.
       *
-     * @param object
+     * @param object the object to be transformed
       * @return array of bytes representing the given object
       * @throws IOException when serialization system throws one
       */
=======================================
---  
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PPaintContext.java
      
Fri Oct  9 10:12:23 2009
+++  
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PPaintContext.java
      
Tue Oct 13 09:36:51 2009
@@ -70,7 +70,7 @@
      /** Used while calculating scale at which rendering is occurring. */
      private static double[] PTS = new double[4];

-    /** PaintContext is associated with this graphics context */
+    /** PaintContext is associated with this graphics context. */
      private final Graphics2D graphics;

      /** Used while computing transparency. */
@@ -82,8 +82,10 @@
      /** Tracks clipping region in local coordinate system. */
      protected PStack localClipStack;

+    /** Stack of cameras through which the node being painted is being  
viewed. */
      protected PStack cameraStack;

+    /** Stack of transforms being applied to the drawing context. */
      protected PStack transformStack;

      /** The current render quality that all rendering should be done in. */
@@ -95,7 +97,6 @@
       * @param graphics graphics context to associate with this paint  
context
       */
      public PPaintContext(final Graphics2D graphics) {
-        super();
          this.graphics = graphics;
          compositeStack = new PStack();
          clipStack = new PStack();
@@ -123,14 +124,10 @@
      public Graphics2D getGraphics() {
          return graphics;
      }
-
-    // ****************************************************************
-    // Context Attributes.
-    // ****************************************************************

      /**
       * Returns the clipping region in the local coordinate system applied  
by
-     * graphics
+     * graphics.
       *
       * @return clipping region in the local coordinate system applied by
       *         graphics
@@ -147,18 +144,14 @@
       * @return scale of the current graphics context's transformation
       */
      public double getScale() {
-        PTS[0] = 0;// x1
-        PTS[1] = 0;// y1
-        PTS[2] = 1;// x2
-        PTS[3] = 0;// y2
+        // x1, y1, x2, y2
+        PTS[0] = 0;
+        PTS[1] = 0;
+        PTS[2] = 1;
+        PTS[3] = 0;
          graphics.getTransform().transform(PTS, 0, PTS, 0, 2);
          return Point2D.distance(PTS[0], PTS[1], PTS[2], PTS[3]);
      }
-
-    // ****************************************************************
-    // Context Attribute Stacks. attributes that can be pushed and
-    // popped.
-    // ****************************************************************

      /**
       * Pushes the camera onto the camera stack.
@@ -186,9 +179,10 @@
      }

      /**
-     * Returns the camera at the top of the camera stack.
+     * Returns the camera at the top of the camera stack, or null if stack  
is
+     * empty.
       *
-     * @return
+     * @return topmost camera on camera stack or null if stack is empty
       */
      public PCamera getCamera() {
          return (PCamera) cameraStack.peek();
@@ -256,20 +250,18 @@
      }

      /**
-     * Pushed the provided transform onto the transform stack.
+     * Pushed the provided transform onto the transform stack if it is not  
null.
       *
-     * @param transform
+     * @param transform will be pushed onto the transform stack if not null
       */
      public void pushTransform(final PAffineTransform transform) {
-        if (transform == null) {
-            return;
-        }
-
-        final Rectangle2D newLocalClip = (Rectangle2D)  
getLocalClip().clone();
-        transform.inverseTransform(newLocalClip, newLocalClip);
-        transformStack.push(graphics.getTransform());
-        localClipStack.push(newLocalClip);
-        graphics.transform(transform);
+        if (transform != null) {
+            final Rectangle2D newLocalClip = (Rectangle2D)  
getLocalClip().clone();
+            transform.inverseTransform(newLocalClip, newLocalClip);
+            transformStack.push(graphics.getTransform());
+            localClipStack.push(newLocalClip);
+            graphics.transform(transform);
+        }
      }

      /**
@@ -307,24 +299,29 @@

          switch (renderQuality) {
              case HIGH_QUALITY_RENDERING:
-                graphics.setRenderingHint(RenderingHints.KEY_ANTIALIASING,  
RenderingHints.VALUE_ANTIALIAS_ON);
-                 
graphics.setRenderingHint(RenderingHints.KEY_TEXT_ANTIALIASING,  
RenderingHints.VALUE_TEXT_ANTIALIAS_ON);
-                graphics.setRenderingHint(RenderingHints.KEY_RENDERING,  
RenderingHints.VALUE_RENDER_QUALITY);
-                 
graphics.setRenderingHint(RenderingHints.KEY_FRACTIONALMETRICS,
-                        RenderingHints.VALUE_FRACTIONALMETRICS_ON);
+                setRenderQualityToHigh();
                  break;

              case LOW_QUALITY_RENDERING:
-                graphics.setRenderingHint(RenderingHints.KEY_ANTIALIASING,  
RenderingHints.VALUE_ANTIALIAS_OFF);
-                graphics
-                        
.setRenderingHint(RenderingHints.KEY_TEXT_ANTIALIASING,  
RenderingHints.VALUE_TEXT_ANTIALIAS_OFF);
-                graphics.setRenderingHint(RenderingHints.KEY_RENDERING,  
RenderingHints.VALUE_RENDER_SPEED);
-                 
graphics.setRenderingHint(RenderingHints.KEY_FRACTIONALMETRICS,
-                        RenderingHints.VALUE_FRACTIONALMETRICS_ON);
+                setRenderQualityToLow();
                  break;
+
              default:
-                throw new RuntimeException(
-                        "Render Quality must be either  
PPaintContext.HIGH_QUALITY_RENDERING or  
PPaintContext.LOW_QUALITY_RENDERING");
+                throw new RuntimeException("Quality must be either  
HIGH_QUALITY_RENDERING or LOW_QUALITY_RENDERING");
          }
      }
-}
+
+    private void setRenderQualityToLow() {
+        graphics.setRenderingHint(RenderingHints.KEY_ANTIALIASING,  
RenderingHints.VALUE_ANTIALIAS_OFF);
+        graphics.setRenderingHint(RenderingHints.KEY_TEXT_ANTIALIASING,  
RenderingHints.VALUE_TEXT_ANTIALIAS_OFF);
+        graphics.setRenderingHint(RenderingHints.KEY_RENDERING,  
RenderingHints.VALUE_RENDER_SPEED);
+        graphics.setRenderingHint(RenderingHints.KEY_FRACTIONALMETRICS,  
RenderingHints.VALUE_FRACTIONALMETRICS_ON);
+    }
+
+    private void setRenderQualityToHigh() {
+        graphics.setRenderingHint(RenderingHints.KEY_ANTIALIASING,  
RenderingHints.VALUE_ANTIALIAS_ON);
+        graphics.setRenderingHint(RenderingHints.KEY_TEXT_ANTIALIASING,  
RenderingHints.VALUE_TEXT_ANTIALIAS_ON);
+        graphics.setRenderingHint(RenderingHints.KEY_RENDERING,  
RenderingHints.VALUE_RENDER_QUALITY);
+        graphics.setRenderingHint(RenderingHints.KEY_FRACTIONALMETRICS,  
RenderingHints.VALUE_FRACTIONALMETRICS_ON);
+    }
+}
=======================================
---  
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PPickPath.java 
 
Thu Oct  8 21:24:11 2009
+++  
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PPickPath.java 
 
Tue Oct 13 09:36:51 2009
@@ -142,6 +142,8 @@
      /**
       * Get the bottom node on the pick path node stack. That is the last  
node to
       * be picked.
+     *
+     * @return the bottom node on the pick path
       */
      public PNode getPickedNode() {
          return (PNode) nodeStack.peek();
@@ -153,9 +155,11 @@

      /**
       * Return the next node that will be picked after the current picked  
node.
-     * For instance of you have two overlaping children nodes then the  
topmost
+     * For instance of you have two overlapping children nodes then the  
topmost
       * child will always be picked first, use this method to find the  
covered
       * child. Return the camera when no more visual will be picked.
+     *
+     * @return next node to picked after the picked node
       */
      public PNode nextPickedNode() {
          final PNode picked = getPickedNode();
@@ -195,6 +199,8 @@
      /**
       * Get the top camera on the pick path. This is the camera that  
originated
       * the pick action.
+     *
+     * @return the topmost camera of this pick pack
       */
      public PCamera getTopCamera() {
          return topCamera;
@@ -203,19 +209,25 @@
      /**
       * Get the bottom camera on the pick path. This may be different then  
the
       * top camera if internal cameras are in use.
+     *
+     * @return the camera closest to the picked node
       */
      public PCamera getBottomCamera() {
          if (bottomCamera == null) {
-            for (int i = nodeStack.size() - 1; i >= 0; i--) {
-                final PNode each = (PNode) nodeStack.get(i);
-                if (each instanceof PCamera) {
-                    bottomCamera = (PCamera) each;
-                    return bottomCamera;
-                }
-            }
+            bottomCamera = calculateBottomCamera();
          }
          return bottomCamera;
      }
+
+    private PCamera calculateBottomCamera() {
+        for (int i = nodeStack.size() - 1; i >= 0; i--) {
+            final PNode each = (PNode) nodeStack.get(i);
+            if (each instanceof PCamera) {
+                return (PCamera) each;
+            }
+        }
+        return null;
+    }

      /**
       * Returns a reference to the node stack. Be Careful!
@@ -238,10 +250,11 @@
       * @return scale at which interaction is occurring.
       */
      public double getScale() {
-        PTS[0] = 0;// x1
-        PTS[1] = 0;// y1
-        PTS[2] = 1;// x2
-        PTS[3] = 0;// y2
+        // x1, y1, x2, y3
+        PTS[0] = 0;
+        PTS[1] = 0;
+        PTS[2] = 1;
+        PTS[3] = 0;

          final int count = transformStack.size();
          for (int i = 0; i < count; i++) {
@@ -354,7 +367,10 @@
       * the local coordinates of the given node.
       *
       * @param canvasPoint point to be transformed
-     * @param nodeOnPath node into which the point is to be transformed  
iteratively through the pickpath
+     * @param nodeOnPath node into which the point is to be transformed
+     *            iteratively through the pick path
+     *
+     * @return transformed canvasPoint in local coordinates of the picked  
node
       */
      public Point2D canvasToLocal(final Point2D canvasPoint, final PNode  
nodeOnPath) {
          return  
getPathTransformTo(nodeOnPath).inverseTransform(canvasPoint, canvasPoint);
@@ -366,7 +382,11 @@
       * the local coordinates of the given node.
       *
       * @param canvasDimension dimension to be transformed
-     * @param nodeOnPath node into which the dimension is to be  
transformed iteratively through the stack
+     * @param nodeOnPath node into which the dimension is to be transformed
+     *            iteratively through the stack
+     *
+     * @return transformed canvasDimension in local coordinates of the  
picked
+     *         node
       */
      public Dimension2D canvasToLocal(final Dimension2D canvasDimension,  
final PNode nodeOnPath) {
          return  
getPathTransformTo(nodeOnPath).inverseTransform(canvasDimension,  
canvasDimension);
@@ -378,7 +398,10 @@
       * the local coordinates of the given node.
       *
       * @param canvasRectangle rectangle to be transformed
-     * @param nodeOnPath node into which the rectangle is to be  
transformed iteratively through the stack
+     * @param nodeOnPath node into which the rectangle is to be transformed
+     *            iteratively through the stack
+     * @return transformed canvasRectangle in local coordinates of the  
picked
+     *         node
       */
      public Rectangle2D canvasToLocal(final Rectangle2D canvasRectangle,  
final PNode nodeOnPath) {
          return  
getPathTransformTo(nodeOnPath).inverseTransform(canvasRectangle,  
canvasRectangle);
=======================================
---  
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PUtil.java     
 
Thu Oct  8 21:24:11 2009
+++  
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PUtil.java     
 
Tue Oct 13 09:36:51 2009
@@ -58,10 +58,20 @@
       * pass between steps.
       */
      public static long DEFAULT_ACTIVITY_STEP_RATE = 20;
+
+    /** Rate in milliseconds at which the activity timer will get invoked.  
*/
      public static int ACTIVITY_SCHEDULER_FRAME_DELAY = 10;
+
+    /** An iterator that iterates over an empty collection. */
      public static Iterator NULL_ITERATOR =  
Collections.EMPTY_LIST.iterator();

+    /**
+     * Used when persisting paths to an object stream. Used to mark the  
end of
+     * the path.
+     */
      private static final int PATH_TERMINATOR = -1;
+
+    /** A utility enumeration with no elements. */
      public static Enumeration NULL_ENUMERATION = new Enumeration() {
          public boolean hasMoreElements() {
              return false;
@@ -114,9 +124,10 @@
       * Serializes the given stroke object to the object output stream  
provided.
       * By default strokes are not serializable. This method solves that  
problem.
       *
-     * @param stroke stroke to be serialized
-     * @param out stream to which the stroke is to be serialized.
-     * @throws IOException
+     * @param stroke stroke to be serialize
+     * @param out stream to which the stroke is to be serialized
+     * @throws IOException can occur if exception occurs with underlying  
output
+     *             stream
       */
      public static void writeStroke(final Stroke stroke, final  
ObjectOutputStream out) throws IOException {
          if (stroke instanceof Serializable) {
@@ -162,8 +173,9 @@
       *
       * @param in stream from which Stroke is to be read
       * @return a stroke object
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @throws IOException occurs if an exception occurs reading from in  
stream
+     * @throws ClassNotFoundException should never happen, but can if  
somehow
+     *             the stroke class is not on the classpath
       */
      public static Stroke readStroke(final ObjectInputStream in) throws  
IOException, ClassNotFoundException {
          final boolean wroteStroke = in.readBoolean();
@@ -205,8 +217,9 @@
       *
       * @param in stream from which to read the path.
       * @return reconstituted path
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @throws IOException if an unknown path type is read from the stream
+     * @throws ClassNotFoundException should never happen, but can if  
somehow
+     *             the classpath is seriously messed up
       */
      public static GeneralPath readPath(final ObjectInputStream in) throws  
IOException, ClassNotFoundException {
          final GeneralPath path = new GeneralPath();
@@ -240,7 +253,7 @@
                      return path;

                  default:
-                    throw new IOException();
+                    throw new IOException("Unknown path type encountered  
while deserializing path.");
              }
          }
      }
@@ -250,7 +263,8 @@
       *
       * @param path path to be serialized
       * @param out stream to which the path should be serialized
-     * @throws IOException
+     * @throws IOException if unknown path segment type is encountered, or  
an
+     *             exception occurs writing to the output stream
       */
      public static void writePath(final GeneralPath path, final  
ObjectOutputStream out) throws IOException {
          final PathIterator i = path.getPathIterator(null);
@@ -293,7 +307,7 @@
                      break;

                  default:
-                    throw new IOException();
+                    throw new IOException("Unknown path type encountered  
while serializing path.");
              }

              i.next();

--~--~---------~--~----~------------~-------~--~----~
Piccolo2D Developers Group: http://groups.google.com/group/piccolo2d-dev?hl=en
-~----------~----~----~----~------~----~------~--~---

Reply via email to