Index: /trunk/src/org/openstreetmap/josm/gui/mappaint/ElemStyles.java
===================================================================
--- /trunk/src/org/openstreetmap/josm/gui/mappaint/ElemStyles.java	(revision 11136)
+++ /trunk/src/org/openstreetmap/josm/gui/mappaint/ElemStyles.java	(revision 11137)
@@ -35,4 +35,24 @@
 import org.openstreetmap.josm.tools.Utils;
 
+/**
+ * Generates a list of {@link StyleElement}s for a primitive, to
+ * be drawn on the map.
+ * There are several steps to derive the list of elements for display:
+ * <ol>
+ * <li>{@link #generateStyles(OsmPrimitive, double, boolean)} applies the
+ * {@link StyleSource}s one after another to get a key-value map of MapCSS
+ * properties. Then a preliminary set of StyleElements is derived from the
+ * properties map.</li>
+ * <li>{@link #getImpl(OsmPrimitive, double, NavigatableComponent)} handles the
+ * different forms of multipolygon tagging.</li>
+ * <li>{@link #getStyleCacheWithRange(OsmPrimitive, double, NavigatableComponent)}
+ * adds a default StyleElement for primitives that would be invisible otherwise.
+ * (For example untagged nodes and ways.)</li>
+ * </ol>
+ * The results are cached with respect to the current scale.
+ *
+ * Use {@link #setStyleSources(Collection)} to select the StyleSources that are
+ * applied.
+ */
 public class ElemStyles implements PreferenceChangedListener {
     private final List<StyleSource> styleSources;
Index: /trunk/src/org/openstreetmap/josm/gui/mappaint/Keyword.java
===================================================================
--- /trunk/src/org/openstreetmap/josm/gui/mappaint/Keyword.java	(revision 11136)
+++ /trunk/src/org/openstreetmap/josm/gui/mappaint/Keyword.java	(revision 11137)
@@ -5,4 +5,12 @@
 import java.util.Objects;
 
+/**
+ * A MapCSS keyword.
+ *
+ * For example "<code>round</code>" is a keyword in
+ * <pre>linecap: round;</pre>
+ * Keywords are similar to a Java enum value. In accordance with the CSS
+ * specification, they are parsed case insensitive.
+ */
 public class Keyword {
     public final String val;
Index: /trunk/src/org/openstreetmap/josm/gui/mappaint/MapPaintStyles.java
===================================================================
--- /trunk/src/org/openstreetmap/josm/gui/mappaint/MapPaintStyles.java	(revision 11136)
+++ /trunk/src/org/openstreetmap/josm/gui/mappaint/MapPaintStyles.java	(revision 11137)
@@ -41,9 +41,9 @@
 
 /**
- * This class manages the ElemStyles instance. The object you get with
- * getStyles() is read only, any manipulation happens via one of
- * the wrapper methods here. (readFromPreferences, moveStyles, ...)
+ * This class manages the list of available map paint styles and gives access to
+ * the ElemStyles singleton.
  *
- * On change, mapPaintSylesUpdated() is fired for all listeners.
+ * On change, {@link MapPaintSylesUpdateListener#mapPaintStylesUpdated()} is fired
+ * for all listeners.
  */
 public final class MapPaintStyles {
@@ -60,6 +60,10 @@
 
     /**
-     * Returns the {@link ElemStyles} instance.
-     * @return the {@code ElemStyles} instance
+     * Returns the {@link ElemStyles} singleton instance.
+     *
+     * The returned object is read only, any manipulation happens via one of
+     * the other wrapper methods in this class. ({@link #readFromPreferences},
+     * {@link #moveStyles}, ...)
+     * @return the {@code ElemStyles} singleton instance
      */
     public static ElemStyles getStyles() {