utils.pool: remove debug + docs

vtm/src/org/oscim/utils/pool/Inlist.java

@@ -19,15 +19,31 @@ package org.oscim.utils.pool;
  * Instead of using an additional list to hold pool items just extend this
  * class.
  * 
- * Also handy for objects that exist in only *one list* at a time.
+ * Also handy for objects that exist in only *one list* at a time, if you
- * */
+ * are *REALLY* sure about it. Better do not use it! :)
-
+ */
 public class Inlist<T extends Inlist<T>> {
 
-	private final static boolean debug = false;
-
 	public T next;
 
+	/**
+	 * Push 'item' onto 'list'.
+	 * 
+	 * @param list the list
+	 * @param item the item
+	 * @return the new head of 'list' (item)
+	 */
+	public static <T extends Inlist<T>> T push(T list, T item) {
+		item.next = list;
+		return item;
+	}
+
+	/**
+	 * Get size of 'list'.
+	 * 
+	 * @param list the list
+	 * @return the number of items in 'list'
+	 */
 	static <T extends Inlist<T>> int size(T list) {
 		int count = 0;
 		for (Inlist<T> l = list; l != null; l = l.next)
@@ -35,14 +51,21 @@ public class Inlist<T extends Inlist<T>> {
 		return count;
 	}
 
+	/**
+	 * Removes the 'item' from 'list'.
+	 * 
+	 * @param list the list
+	 * @param item the item
+	 * @return the new head of 'list'
+	 */
 	public static <T extends Inlist<T>> T remove(T list, T item) {
 		if (item == list) {
 			T head = item.next;
 			item.next = null;
 			return head;
 		}
-		for (Inlist<T> prev = list, it = list.next; it != null; it = it.next) {
 
+		for (Inlist<T> prev = list, it = list.next; it != null; it = it.next) {
 			if (it == item) {
 				prev.next = item.next;
 				item.next = null;
@@ -54,6 +77,13 @@ public class Inlist<T extends Inlist<T>> {
 		return list;
 	}
 
+	/**
+	 * Gets the 'item' with index 'i'.
+	 * 
+	 * @param list the list
+	 * @param i the index
+	 * @return the item or null
+	 */
 	public static <T extends Inlist<T>> T get(T list, int i) {
 		if (i < 0)
 			return null;
@@ -67,31 +97,18 @@ public class Inlist<T extends Inlist<T>> {
 		return null;
 	}
 
-	//	public static <T extends Inlist<T>> T insertAt(T list, T item, int i){
+	/**
-	//		if (i < 0)
+	 * Append 'item' to 'list'. 'item' may not be in another list,
-	//			return null;
+	 * i.e. item.next must be null
-	//
+	 * 
-	//		while (--i > 0 && list != null)
+	 * @param list the list
-	//			list = list.next;
+	 * @param item the item
-	//
+	 * @return the new head of 'list'
-	//		if (i == 0)
+	 */
-	//			return list;
-	//
-	//		return null;
-	//	}
-
-	public static <T extends Inlist<T>> T push(T list, T item) {
-		item.next = list;
-		return item;
-	}
-
 	public static <T extends Inlist<T>> T appendItem(T list, T item) {
 
-		if (debug) {
+		if (item.next != null)
-			if (item.next != null) {
+			throw new IllegalArgumentException("'item' is list");
-				throw new IllegalArgumentException("item is list");
-			}
-		}
 
 		if (list == null)
 			return item;
@@ -106,28 +123,40 @@ public class Inlist<T extends Inlist<T>> {
 		return list;
 	}
 
-	public static <T extends Inlist<T>> T appendList(T list, T list2) {
+	/**
+	 * Append list 'other' to 'list'.
+	 * 
+	 * @param list the list
+	 * @param other the other
+	 * @return the head of 'list'
+	 */
+	public static <T extends Inlist<T>> T appendList(T list, T other) {
 
 		if (list == null)
-			return list2;
+			return other;
 
-		if (list == list2)
+		if (list == other)
 			return list;
 
 		Inlist<T> it = list;
 
 		while (it.next != null) {
-			if (it.next == list2)
+			if (it.next == other)
-				// hmmmm, already in list
+				throw new IllegalArgumentException("'other' alreay in 'list'");
-				return list;
 
 			it = it.next;
 		}
-		it.next = list2;
+		it.next = other;
 
 		return list;
 	}
 
+	/**
+	 * Get last item in from list.
+	 * 
+	 * @param list the list
+	 * @return the last item
+	 */
 	public static <T extends Inlist<T>> T last(T list) {
 		while (list != null) {
 			if (list.next == null)
@@ -137,17 +166,21 @@ public class Inlist<T extends Inlist<T>> {
 		return null;
 	}
 
+	/**
+	 * Prepend 'item' relative to 'other'.
+	 * 
+	 * @param list the list
+	 * @param item the item
+	 * @param other the other list
+	 * @return the new head of list
+	 */
 	public static <T extends Inlist<T>> T prependRelative(T list, T item, T other) {
 
-		if (debug) {
+		if (item.next != null)
-			if (item.next != null) {
+			throw new IllegalArgumentException("'item' is list");
-				// warn
-				item.next = null;
-			}
-		}
 
 		if (list == null)
-			throw new IllegalArgumentException("Inlist.prependRelative 'list' is null");
+			throw new IllegalArgumentException("'list' is null");
 
 		if (list == other) {
 			item.next = list;
@@ -160,7 +193,7 @@ public class Inlist<T extends Inlist<T>> {
 			it = it.next;
 
 		if (it == null)
-			throw new IllegalArgumentException("Inlist.prependRelative 'other' not in 'list'");
+			throw new IllegalArgumentException("'other' not in 'list'");
 
 		item.next = it.next;
 		it.next = item;

vtm/src/org/oscim/utils/pool/SyncPool.java

@@ -59,6 +59,11 @@ public abstract class SyncPool<T extends Inlist<T>> {
 
 	}
 
+	/**
+	 * Creates the item. To be implemented by subclass.
+	 * 
+	 * @return the item
+	 */
 	protected abstract T createItem();
 
 	public void release(T item) {
@@ -82,6 +87,12 @@ public abstract class SyncPool<T extends Inlist<T>> {
 		}
 	}
 
+	/**
+	 * Release all items from 'item'. Do not use the
+	 * 'item' reference afterwards!
+	 * 
+	 * @param item the item (or list or items)
+	 */
 	public void releaseAll(T item) {
 		if (item == null)
 			return;
@@ -116,6 +127,12 @@ public abstract class SyncPool<T extends Inlist<T>> {
 		}
 	}
 
+	/**
+	 * Gets an 'item' from pool, if pool is empty a new
+	 * item will be created by createItem().
+	 * 
+	 * @return the item
+	 */
 	public T get() {
 
 		synchronized (this) {