added more links to test code inside the kdoc and tidied up the tests a little so they look a bit nicer and more self contained in the documentation

libraries/stdlib/src/kotlin/JavaIterables.kt

@@ -16,7 +16,11 @@ inline fun <T> java.lang.Iterable<T>.any(predicate: (T)-> Boolean) : Boolean {
   return false
 }
 
-/** Returns true if all elements in the collection match the given predicate */
+/**
+ * Returns true if all elements in the collection match the given predicate
+ *
+ * @includeFunction ../../test/CollectionTest.kt all
+ */
 inline fun <T> java.lang.Iterable<T>.all(predicate: (T)-> Boolean) : Boolean {
   for (elem in this) {
     if (!predicate(elem)) {
@@ -26,7 +30,11 @@ inline fun <T> java.lang.Iterable<T>.all(predicate: (T)-> Boolean) : Boolean {
   return true
 }
 
-/** Returns the number of items which match the given predicate  */
+/**
+ * Returns the number of items which match the given predicate
+ *
+ * @includeFunction ../../test/CollectionTest.kt count
+ */
 inline fun <T> java.lang.Iterable<T>.count(predicate: (T)-> Boolean) : Int {
   var answer = 0
   for (elem in this) {
@@ -36,7 +44,11 @@ inline fun <T> java.lang.Iterable<T>.count(predicate: (T)-> Boolean) : Int {
   return answer
 }
 
-/** Returns the first item in the collection which matches the given predicate or null if none matched */
+/**
+ * Returns the first item in the collection which matches the given predicate or null if none matched
+ *
+ * @includeFunction ../../test/CollectionTest.kt find
+ */
 inline fun <T> java.lang.Iterable<T>.find(predicate: (T)-> Boolean) : T? {
   for (elem in this) {
     if (predicate(elem))
@@ -45,7 +57,11 @@ inline fun <T> java.lang.Iterable<T>.find(predicate: (T)-> Boolean) : T? {
   return null
 }
 
-/** Filters all elements in this collection which match the given predicate into the given result collection */
+/**
+ * Filters all elements in this collection which match the given predicate into the given result collection
+ *
+ * @includeFunction ../../test/CollectionTest.kt filterIntoLinkedList
+ */
 inline fun <T, C: Collection<in T>> java.lang.Iterable<T>.filterTo(result: C, predicate: (T)-> Boolean) : C {
   for (elem in this) {
     if (predicate(elem))
@@ -54,18 +70,27 @@ inline fun <T, C: Collection<in T>> java.lang.Iterable<T>.filterTo(result: C, pr
   return result
 }
 
-/** Filters all the null elements in this collection into the given result collection */
+/**
+ * Filters all the null elements in this collection into the given result collection
+ *
+ * @includeFunction ../../test/CollectionTest.kt filterNotNullIntoLinkedList
+ */
 inline fun <T, C: Collection<in T>> java.lang.Iterable<T?>?.filterNotNullTo(result: C) : C {
     if (this != null) {
         for (elem in this) {
-            if (elem != null)
+            if (elem != null) {
                 result.add(elem)
+            }
         }
     }
     return result
 }
 
-/** Returns a new collection containing all elements in this collection which do not match the given predicate */
+/**
+ * Returns a new collection containing all elements in this collection which do not match the given predicate
+ *
+ * @includeFunction ../../test/CollectionTest.kt filterNotIntoLinkedList
+ */
 inline fun <T, C: Collection<in T>> java.lang.Iterable<T>.filterNotTo(result: C, predicate: (T)-> Boolean) : C {
   for (elem in this) {
     if (!predicate(elem))
@@ -75,9 +100,10 @@ inline fun <T, C: Collection<in T>> java.lang.Iterable<T>.filterNotTo(result: C,
 }
 
 /**
-  * Returns the result of transforming each item in the collection to a one or more values which
+ * Returns the result of transforming each item in the collection to a one or more values which
-  * are concatenated together into a single collection
+ * are concatenated together into a single collection
-  */
+ */
+// TODO  * @includeFunction ../../test/CollectionTest.kt flatMapTo
 inline fun <T, R> java.lang.Iterable<T>.flatMapTo(result: Collection<R>, transform: (T)-> Collection<R>) : Collection<R> {
   for (elem in this) {
     val coll = transform(elem)
@@ -90,7 +116,11 @@ inline fun <T, R> java.lang.Iterable<T>.flatMapTo(result: Collection<R>, transfo
   return result
 }
 
-/** Performs the given operation on each element inside the collection */
+/**
+ * Performs the given operation on each element inside the collection
+ *
+ * @includeFunction ../../test/CollectionTest.kt forEach
+ */
 inline fun <T> java.lang.Iterable<T>.forEach(operation: (element: T) -> Unit) {
   for (elem in this)
     operation(elem)
@@ -99,8 +129,7 @@ inline fun <T> java.lang.Iterable<T>.forEach(operation: (element: T) -> Unit) {
 /**
  * Folds all the values from from left to right with the initial value to perform the operation on sequential pairs of values
  *
- * For example to sum together all numeric values in a collection of numbers it would be
+ * @includeFunction ../../test/CollectionTest.kt fold
- * {code}val total = numbers.fold(0){(a, b) -> a + b}{code}
  */
 inline fun <T> java.lang.Iterable<T>.fold(initial: T, operation: (it: T, it2: T) -> T): T {
   var answer = initial
@@ -112,6 +141,8 @@ inline fun <T> java.lang.Iterable<T>.fold(initial: T, operation: (it: T, it2: T)
 
 /**
  * Folds all the values from right to left with the initial value to perform the operation on sequential pairs of values
+ *
+ * @includeFunction ../../test/CollectionTest.kt foldRight
  */
 inline fun <T> java.lang.Iterable<T>.foldRight(initial: T, operation: (it: T, it2: T) -> T): T {
   val reversed = this.reverse()
@@ -121,6 +152,8 @@ inline fun <T> java.lang.Iterable<T>.foldRight(initial: T, operation: (it: T, it
 /**
  * Iterates through the collection performing the transformation on each element and using the result
  * as the key in a map to group elements by the result
+ *
+ * @includeFunction ../../test/CollectionTest.kt groupBy
  */
 inline fun <T,K> java.lang.Iterable<T>.groupBy(result: Map<K,List<T>> = HashMap<K,List<T>>(), toKey: (T)-> K) : Map<K,List<T>> {
   for (elem in this) {
@@ -132,7 +165,11 @@ inline fun <T,K> java.lang.Iterable<T>.groupBy(result: Map<K,List<T>> = HashMap<
 }
 
 
-/** Creates a String from all the elements in the collection, using the seperator between them and using the given prefix and postfix if supplied */
+/**
+ * Creates a String from all the elements in the collection, using the seperator between them and using the given prefix and postfix if supplied
+ *
+ * @includeFunction ../../test/CollectionTest.kt join
+ */
 inline fun <T> java.lang.Iterable<T>.join(separator: String, prefix: String = "", postfix: String = "") : String {
   val buffer = StringBuilder(prefix)
   var first = true
@@ -147,7 +184,11 @@ inline fun <T> java.lang.Iterable<T>.join(separator: String, prefix: String = ""
   return buffer.toString().sure()
 }
 
-/** Returns a reversed List of this collection */
+/**
+ * Returns a reversed List of this collection
+ *
+ * @includeFunction ../../test/CollectionTest.kt reverse
+ */
 inline fun <T> java.lang.Iterable<T>.reverse() : List<T> {
   val answer = LinkedList<T>()
   for (elem in this) {
@@ -156,14 +197,20 @@ inline fun <T> java.lang.Iterable<T>.reverse() : List<T> {
   return answer
 }
 
-/** Copies the collection into the given collection */
+/**
+ * Copies the collection into the given collection
+ *
+ * @includeFunction ../../test/CollectionTest.kt reverse
+ */
 inline fun <T, C: Collection<T>> java.lang.Iterable<T>.to(result: C) : C {
   for (elem in this)
     result.add(elem)
   return result
 }
 
-/** Converts the collection into a LinkedList */
+/**
+ * Converts the collection into a LinkedList
+ */
 inline fun <T> java.lang.Iterable<T>.toLinkedList() : LinkedList<T> = this.to(LinkedList<T>())
 
 /**  Converts the collection into a List */

libraries/stdlib/test/CollectionTest.kt

@@ -8,18 +8,8 @@ import org.junit.Test
 
 class CollectionTest {
 
-    class IterableWrapper<T>(collection : java.lang.Iterable<T>) : java.lang.Iterable<T> {
-        private val collection = collection
-
-        override fun iterator(): java.util.Iterator<T> {
-            return collection.iterator().sure()
-        }
-    }
-
-
-    val data = arrayList("foo", "bar")
-
     Test fun any() {
+        val data = arrayList("foo", "bar")
         assertTrue {
             data.any{it.startsWith("f")}
         }
@@ -29,6 +19,7 @@ class CollectionTest {
     }
 
     Test fun all() {
+        val data = arrayList("foo", "bar")
         assertTrue {
             data.all{it.length == 3}
         }
@@ -38,13 +29,14 @@ class CollectionTest {
     }
 
     Test fun count() {
+        val data = arrayList("foo", "bar")
         assertEquals(1, data.count{it.startsWith("b")})
         assertEquals(2, data.count{it.size == 3})
     }
 
     Test fun filter() {
+        val data = arrayList("foo", "bar")
         val foo = data.filter{it.startsWith("f")}
-
         assertTrue {
             foo.all{it.startsWith("f")}
         }
@@ -53,6 +45,7 @@ class CollectionTest {
     }
 
     Test fun filterNot() {
+        val data = arrayList("foo", "bar")
         val foo = data.filterNot{it.startsWith("b")}
 
         assertTrue {
@@ -62,8 +55,9 @@ class CollectionTest {
         assertEquals(arrayList("foo"), foo)
     }
 
+    // TODO would be nice to avoid the <String>
     Test fun filterIntoLinkedList() {
-        // TODO would be nice to avoid the <String>
+        val data = arrayList("foo", "bar")
         val foo = data.filterTo(linkedList<String>()){it.startsWith("f")}
 
         assertTrue {
@@ -77,7 +71,37 @@ class CollectionTest {
         }
     }
 
+    // TODO would be nice to avoid the <String>
+    Test fun filterNotIntoLinkedList() {
+        val data = arrayList("foo", "bar")
+        val foo = data.filterNotTo(linkedList<String>()){it.startsWith("f")}
+
+        assertTrue {
+            foo.all{!it.startsWith("f")}
+        }
+        assertEquals(1, foo.size)
+        assertEquals(linkedList("bar"), foo)
+
+        assertTrue {
+            foo is LinkedList<String>
+        }
+    }
+
+    // TODO would be nice to avoid the <String>
+    Test fun filterNotNullIntoLinkedList() {
+        val data = arrayList(null, "foo", null, "bar")
+        val foo = data.filterNotNullTo(linkedList<String>())
+
+        assertEquals(2, foo.size)
+        assertEquals(linkedList("foo", "bar"), foo)
+
+        assertTrue {
+            foo is LinkedList<String>
+        }
+    }
+
     Test fun filterIntoSet() {
+        val data = arrayList("foo", "bar")
         // TODO would be nice to avoid the <String>
         val foo = data.filterTo(hashSet<String>()){it.startsWith("f")}
 
@@ -93,6 +117,7 @@ class CollectionTest {
     }
 
     Test fun filterIntoSortedSet() {
+        val data = arrayList("foo", "bar")
         // TODO would be nice to avoid the <String>
         val sorted = data.filterTo(sortedSet<String>()){it.length == 3}
         assertEquals(2, sorted.size)
@@ -103,6 +128,7 @@ class CollectionTest {
     }
 
     Test fun find() {
+        val data = arrayList("foo", "bar")
         val x = data.find{it.startsWith("x")}
         assertNull(x)
         fails {
@@ -115,6 +141,7 @@ class CollectionTest {
     }
 
     Test fun flatMap() {
+        val data = arrayList("foo", "bar")
         val characters = arrayList('f', 'o', 'o', 'b', 'a', 'r')
         // TODO figure out how to get a line like this to compile :)
         /*
@@ -129,18 +156,27 @@ class CollectionTest {
         }
     }
 
-    Test fun foreach() {
+    Test fun forEach() {
+        val data = arrayList("foo", "bar")
         var count = 0
         data.forEach{ count += it.length }
         assertEquals(6, count)
     }
 
+
+    /*
+    // TODO would be nice to be able to write this as this
+    //numbers.fold(0){it + it2}
+    numbers.fold(0){(it, it2) -> it + it2}
+
+    // TODO would be nice to be able to write this as this
+    // numbers.map{it.toString()}.fold(""){it + it2}
+    numbers.map<Int, String>{it.toString()}.fold(""){(it, it2) -> it + it2}
+    */
     Test fun fold() {
+        // lets calculate the sum of some numbers
         expect(10) {
             val numbers = arrayList(1, 2, 3, 4)
-
-            // TODO would be nice to be able to write this as this
-            //numbers.fold(0){it + it2}
             numbers.fold(0){(it, it2) -> it + it2}
         }
 
@@ -149,50 +185,48 @@ class CollectionTest {
             numbers.fold(0){(it, it2) -> it + it2}
         }
 
+        // lets concatenate some strings
         expect("1234") {
             val numbers = arrayList(1, 2, 3, 4)
-
-            // TODO would be nice to be able to write this as this
-            // numbers.map{it.toString()}.fold(""){it + it2}
             numbers.map<Int, String>{it.toString()}.fold(""){(it, it2) -> it + it2}
         }
     }
 
+    /*
+        // TODO would be nice to be able to write this as this
+        // numbers.map{it.toString()}.foldRight(""){it + it2}
+        numbers.map<Int, String>{it.toString()}.foldRight(""){(it, it2) -> it + it2}
+    */
     Test fun foldRight() {
         expect("4321") {
             val numbers = arrayList(1, 2, 3, 4)
-
-            // TODO would be nice to be able to write this as this
-            // numbers.map{it.toString()}.foldRight(""){it + it2}
             numbers.map<Int, String>{it.toString()}.foldRight(""){(it, it2) -> it + it2}
         }
     }
 
 
+    /*
+        TODO inference engine should not need this type info?
+        val byLength = words.groupBy<String, Int>{it.length}
+    */
     Test fun groupBy() {
         val words = arrayList("a", "ab", "abc", "def", "abcd")
-        /*
-        TODO inference engine should not need this type info?
-        */
         val byLength = words.groupBy<String, Int>{it.length}
         assertEquals(4, byLength.size())
 
-        println("Grouped by length is: $byLength")
-        /*
-         TODO compiler bug...
-
         val l3 = byLength.getOrElse(3, {ArrayList<String>()})
         assertEquals(2, l3.size)
-        */
 
     }
 
     Test fun join() {
+        val data = arrayList("foo", "bar")
         val text = data.join("-", "<", ">")
         assertEquals("<foo-bar>", text)
     }
 
     Test fun map() {
+        val data = arrayList("foo", "bar")
         /**
           TODO compiler bug
           we should be able to remove the explicit type on the function
@@ -207,6 +241,7 @@ class CollectionTest {
     }
 
     Test fun reverse() {
+        val data = arrayList("foo", "bar")
         val rev = data.reverse()
         assertEquals(arrayList("bar", "foo"), rev)
     }
@@ -225,6 +260,7 @@ class CollectionTest {
     }
 
     Test fun toArray() {
+        val data = arrayList("foo", "bar")
         val arr = data.toArray()
         println("Got array ${arr}")
         todo {
@@ -235,12 +271,14 @@ class CollectionTest {
     }
 
     Test fun simpleCount() {
+        val data = arrayList("foo", "bar")
         assertEquals(2, data.count())
         assertEquals(3, hashSet(12, 14, 15).count())
         assertEquals(0, ArrayList<Double>().count())
     }
 
     Test fun last() {
+        val data = arrayList("foo", "bar")
         assertEquals("bar", data.last())
         assertEquals(25, arrayList(15, 19, 20, 25).last())
         // assertEquals(19, TreeSet(arrayList(90, 47, 19)).first())
@@ -277,6 +315,7 @@ class CollectionTest {
     }
 
     Test fun indices() {
+        val data = arrayList("foo", "bar")
         val indices = data.indices
         assertEquals(0, indices.start)
         assertEquals(1, indices.end)
@@ -285,6 +324,7 @@ class CollectionTest {
     }
 
     Test fun contains() {
+        val data = arrayList("foo", "bar")
         assertTrue(data.contains("foo"))
         assertTrue(data.contains("bar"))
         assertFalse(data.contains("some"))
@@ -299,4 +339,13 @@ class CollectionTest {
         //    assertTrue(IterableWrapper(hashSet(45, 14, 13)).contains(14))
         //    assertFalse(IterableWrapper(linkedList<Int>()).contains(15))
     }
+
+
+    class IterableWrapper<T>(collection : java.lang.Iterable<T>) : java.lang.Iterable<T> {
+        private val collection = collection
+
+        override fun iterator(): java.util.Iterator<T> {
+            return collection.iterator().sure()
+        }
+    }
 }