Add documentation

src/de/tudarmstadt/maki/simonstrator/api/common/graph/GraphElementPropertyBasedComparator.java

 /*
- * Copyright (c) 2005-2010 KOM � Multimedia Communications Lab
+ * Copyright (c) 2005-2010 KOM - Multimedia Communications Lab
  *
  * This file is part of Simonstrator.KOM.
  * 
@@ -22,28 +22,66 @@ package de.tudarmstadt.maki.simonstrator.api.common.graph;
 
 import java.util.Comparator;
 
-//TODO@rkluge: Test me 
+/**
+ * This comparator compares {@link IElement}s based on the configured numeric
+ * {@link GraphElementProperty} (see also
+ * {@link #GraphElementPropertyBasedComparator(GraphElementProperty)}).
+ * 
+ * @author Roland Kluge Original implementation
+ */
 public class GraphElementPropertyBasedComparator implements Comparator<IElement> {
 
-	private final GraphElementProperty<? extends Number> graphElementProperty;
+	private final GraphElementProperty<? extends Number> property;
 
-	public GraphElementPropertyBasedComparator(
-			final GraphElementProperty<? extends Number> graphElementProperty) {
-		this.graphElementProperty = graphElementProperty;
+	/**
+	 * Initializes the {@link GraphElementProperty} to use for comparing
+	 * {@link IElement}s
+	 * 
+	 * @param property
+	 *            the property to use
+	 */
+	public GraphElementPropertyBasedComparator(final GraphElementProperty<? extends Number> property) {
+		this.property = property;
+	}
+
+	/**
+	 * Returns the configured property
+	 */
+	public GraphElementProperty<? extends Number> getProperty() {
+		return property;
 	}
 
+	/**
+	 * Compares the two elements based on the configured
+	 * {@link GraphElementProperty}.
+	 * 
+	 * Both elements need to provide the property, otherwise, an exception is
+	 * thrown.
+	 * 
+	 * The result is equivalent to comparing the double values of both elements
+	 * using {@link Double#compare(double, double)}.
+	 * 
+	 * @param o1
+	 *            the first element
+	 * @param o2
+	 *            the second element
+	 * @return the comparison result
+	 * 
+	 * @throws MissingGraphElementPropertyException
+	 *             if one of the elements does not expose the property
+	 */
 	@Override
-	public int compare(IElement o1, IElement o2) {
-		Number p1 = o1.getProperty(graphElementProperty);
-		Number p2 = o2.getProperty(graphElementProperty);
+	public int compare(final IElement o1, final IElement o2) {
+
+		final Number p1 = o1.getProperty(property);
+		final Number p2 = o2.getProperty(property);
+
 		if (p1 == null)
-			throw new IllegalArgumentException(
-					String.format("Element %s does not have required property %s", o1, graphElementProperty));
+			throw new MissingGraphElementPropertyException(o1, property);
 		if (p2 == null)
-			throw new IllegalArgumentException(
-					String.format("Element %s does not have required property %s", o2, graphElementProperty));
+			throw new MissingGraphElementPropertyException(o2, property);
 
-		return p1.doubleValue() == p2.doubleValue() ? 0 : (p1.doubleValue() < p2.doubleValue() ? -1 : 1);
+		return Double.compare(p1.doubleValue(), p2.doubleValue());
 	}
 
 }