Index: trunk/src/org/openstreetmap/josm/actions/JoinAreasAction.java
===================================================================
--- trunk/src/org/openstreetmap/josm/actions/JoinAreasAction.java	(revision 5697)
+++ trunk/src/org/openstreetmap/josm/actions/JoinAreasAction.java	(revision 5698)
@@ -107,7 +107,10 @@
 
 
-    //HelperClass
-    //saves a way and the "inside" side
-    // insideToTheLeft: if true left side is "in", false -right side is "in". Left and right are determined along the orientation of way.
+    /**
+     * HelperClass - saves a way and the "inside" side.
+     *
+     * insideToTheLeft: if true left side is "in", false -right side is "in".
+     * Left and right are determined along the orientation of way.
+     */
     public static class WayInPolygon {
         public final Way way;
@@ -937,7 +940,7 @@
     /**
      * Finds all ways that form inner or outer boundaries.
-     * @param Collection<Way> A list of (splitted) ways that form a multigon and share common end nodes on intersections.
-     * @param Collection<Way> this list is filled with ways that are to be discarded
-     * @return Collection<Collection<Way>> A list of ways that form the outer and inner boundaries of the multigon.
+     * @param multigonWays A list of (splitted) ways that form a multigon and share common end nodes on intersections.
+     * @param discardedResult this list is filled with ways that are to be discarded
+     * @return A list of ways that form the outer and inner boundaries of the multigon.
      */
     public static List<AssembledPolygon> findBoundaryPolygons(Collection<WayInPolygon> multigonWays, List<Way> discardedResult) {
@@ -1034,5 +1037,5 @@
     /**
      * This method checks if polygons have several touching parts and splits them in several polygons.
-     * @param polygon the polygon to process.
+     * @param polygons the polygons to process.
      */
     public static List<AssembledPolygon> fixTouchingPolygons(List<AssembledPolygon> polygons)
Index: trunk/src/org/openstreetmap/josm/data/Preferences.java
===================================================================
--- trunk/src/org/openstreetmap/josm/data/Preferences.java	(revision 5697)
+++ trunk/src/org/openstreetmap/josm/data/Preferences.java	(revision 5698)
@@ -305,4 +305,12 @@
     }
 
+    /**
+     * Get the directory where cached content of any kind should be stored.
+     *
+     * If the directory doesn't exist on the file system, it will be created
+     * by this method.
+     *
+     * @return the cache directory
+     */
     public File getCacheDirectory() {
         if (cacheDirFile != null)
Index: trunk/src/org/openstreetmap/josm/gui/MultiSplitLayout.java
===================================================================
--- trunk/src/org/openstreetmap/josm/gui/MultiSplitLayout.java	(revision 5697)
+++ trunk/src/org/openstreetmap/josm/gui/MultiSplitLayout.java	(revision 5698)
@@ -846,8 +846,11 @@
          * Returns the Split parent of this Node, or null.
          *
+         * This method isn't called getParent(), in order to avoid problems
+         * with recursive object creation when using XmlDecoder.
+         *
          * @return the value of the parent property.
-         * @see #setParent
-         */
-        public Split getParent() { return parent; }
+         * @see #parent_set
+         */
+        public Split parent_get() { return parent; }
 
         /**
@@ -855,8 +858,11 @@
          * value of this property is null.
          *
+         * This method isn't called setParent(), in order to avoid problems
+         * with recursive object creation when using XmlEncoder.
+         *
          * @param parent a Split or null
-         * @see #getParent
-         */
-        public void setParent(Split parent) {
+         * @see #parent_get
+         */
+        public void parent_set(Split parent) {
             this.parent = parent;
         }
@@ -918,5 +924,5 @@
 
         private Node siblingAtOffset(int offset) {
-            Split parent = getParent();
+            Split parent = parent_get();
             if (parent == null)
                 return null;
@@ -1015,9 +1021,9 @@
                 throw new IllegalArgumentException("children must be a non-null List");
             for(Node child : this.children) {
-                child.setParent(null);
+                child.parent_set(null);
             }
             this.children = new ArrayList<Node>(children);
             for(Node child : this.children) {
-                child.setParent(this);
+                child.parent_set(this);
             }
         }
@@ -1125,5 +1131,5 @@
          */
         public final boolean isVertical() {
-            Split parent = getParent();
+            Split parent = parent_get();
             return (parent != null) ? parent.isRowLayout() : false;
         }
Index: trunk/src/org/openstreetmap/josm/tools/Geometry.java
===================================================================
--- trunk/src/org/openstreetmap/josm/tools/Geometry.java	(revision 5697)
+++ trunk/src/org/openstreetmap/josm/tools/Geometry.java	(revision 5698)
@@ -208,4 +208,11 @@
     /**
      * Tests if given point is to the right side of path consisting of 3 points.
+     *
+     * (Imagine the path is continued beyond the endpoints, so you get two rays
+     * starting from lineP2 and going through lineP1 and lineP3 respectively
+     * which divide the plane into two parts. The test returns true, if testPoint
+     * lies in the part that is to the right when traveling in the direction
+     * lineP1, lineP2, lineP3.)
+     *
      * @param lineP1 first point in path
      * @param lineP2 second point in path
@@ -365,4 +372,10 @@
     /**
      * This method tests if secondNode is clockwise to first node.
+     *
+     * The line through the two points commonNode and firstNode divides the
+     * plane into two parts. The test returns true, if secondNode lies in
+     * the part that is to the right when traveling in the direction from
+     * commonNode to firstNode.
+     *
      * @param commonNode starting point for both vectors
      * @param firstNode first vector end node