update the comments so that they appear in the kdoc report

stdlib/ktSrc/Filter.kt

@@ -3,14 +3,10 @@ package kotlin
 import java.util.*
 import java.lang.Iterable
 
-/*
+/** Filters given iterator */
-Filters given iterator
-*/
 inline fun <T> java.util.Iterator<T>.filter(f: (T)-> Boolean) : java.util.Iterator<T> = FilterIterator<T>(this, f)
 
-/*
+/** Create iterator filtering given java.lang.Iterable */
-Create iterator filtering given java.lang.Iterable
-*/
 /*
 inline fun <T> java.lang.Iterable<T>.filter(f: (T)->Boolean) : java.util.Iterator<T> = (iterator() as java.util.Iterator<T>).filter(f)
 */

stdlib/ktSrc/Iterators.kt

@@ -3,36 +3,24 @@ package kotlin.util
 import java.util.*
 import java.util.Iterator
 
-/*
+/** Add iterated elements to given container */
-Add iterated elements to given container
-*/
 fun <T,U: Collection<in T>> java.util.Iterator<T>.to(container: U) : U {
     while(hasNext())
         container.add(next())
     return container
 }
 
-/*
+/** Add iterated elements to java.util.ArrayList */
-Add iterated elements to java.util.ArrayList
-*/
 inline fun <T> java.util.Iterator<T>.toArrayList() = to(ArrayList<T>())
 
-/*
+/** Add iterated elements to java.util.LinkedList */
-Add iterated elements to java.util.LinkedList
-*/
 inline fun <T> java.util.Iterator<T>.toLinkedList() = to(LinkedList<T>())
 
-/*
+/** Add iterated elements to java.util.HashSet */
-Add iterated elements to java.util.HashSet
-*/
 inline fun <T> java.util.Iterator<T>.toHashSet() = to(HashSet<T>())
 
-/*
+/** Add iterated elements to java.util.LinkedHashSet */
-Add iterated elements to java.util.LinkedHashSet
-*/
 inline fun <T> java.util.Iterator<T>.toLinkedHashSet() = to(LinkedHashSet<T>())
 
-/*
+/** Add iterated elements to java.util.TreeSet */
-Add iterated elements to java.util.TreeSet
-*/
 inline fun <T> java.util.Iterator<T>.toTreeSet() = to(TreeSet<T>())

stdlib/ktSrc/JavaIterables.kt

@@ -147,23 +147,23 @@ 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 */
 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 */
+/**  Converts the collection into a List */
 inline fun <T> java.lang.Iterable<T>.toList() : List<T> = this.to(ArrayList<T>())
 
-/* Converts the collection into a Set */
+/** Converts the collection into a Set */
 inline fun <T> java.lang.Iterable<T>.toSet() : Set<T> = this.to(HashSet<T>())
 
-/* Converts the collection into a SortedSet */
+/** Converts the collection into a SortedSet */
 inline fun <T> java.lang.Iterable<T>.toSortedSet() : SortedSet<T> = this.to(TreeSet<T>())
 /**
   TODO figure out necessary variance/generics ninja stuff... :)

stdlib/ktSrc/Standard.kt

@@ -7,17 +7,17 @@ import java.util.HashSet
 import java.util.LinkedHashSet
 import java.util.TreeSet
 
-/*
+/**
 Helper to make jet.Iterator usable in for
 */
 inline fun <T> jet.Iterator<T>.iterator() = this
 
-/*
+/**
 Helper to make java.util.Iterator usable in for
 */
 inline fun <T> java.util.Iterator<T>.iterator() = this
 
-/*
+/**
 Helper to make java.util.Enumeration usable in for
 */
 fun <erased T> java.util.Enumeration<T>.iterator(): Iterator<T> = object: Iterator<T> {
@@ -31,7 +31,7 @@ fun <erased T> java.util.Enumeration<T>.iterator(): Iterator<T> = object: Iterat
  * Extension functions on the standard Kotlin types to behave like the java.lang.* and java.util.* collections
  */
 
-/*
+/**
 Add iterated elements to given container
 */
 fun <T,U: Collection<in T>> Iterator<T>.to(container: U) : U {
@@ -40,32 +40,32 @@ fun <T,U: Collection<in T>> Iterator<T>.to(container: U) : U {
     return container
 }
 
-/*
+/**
 Add iterated elements to java.util.ArrayList
 */
 inline fun <T> Iterator<T>.toArrayList() = to(ArrayList<T>())
 
-/*
+/**
 Add iterated elements to java.util.LinkedList
 */
 inline fun <T> Iterator<T>.toLinkedList() = to(LinkedList<T>())
 
-/*
+/**
 Add iterated elements to java.util.HashSet
 */
 inline fun <T> Iterator<T>.toHashSet() = to(HashSet<T>())
 
-/*
+/**
 Add iterated elements to java.util.LinkedHashSet
 */
 inline fun <T> Iterator<T>.toLinkedHashSet() = to(LinkedHashSet<T>())
 
-/*
+/**
 Add iterated elements to java.util.TreeSet
 */
 inline fun <T> Iterator<T>.toTreeSet() = to(TreeSet<T>())
 
-/*
+/**
 Run function f
 */
 inline fun <T> run(f: () -> T) = f()

stdlib/ktSrc/String.kt

@@ -99,7 +99,7 @@ inline fun String(stringBuilder : java.lang.StringBuilder) = java.lang.String(st
 /** Returns true if the string is not null and not empty */
 inline fun String?.notEmpty() : Boolean = this != null && this.length() > 0
 
-/*
+/**
 Iterator for characters of given CharSequence
 */
 inline fun CharSequence.iterator() : CharIterator = object: jet.CharIterator() {

stdlib/ktSrc/concurrent/Locks.kt

@@ -5,7 +5,7 @@ import java.util.concurrent.locks.ReadWriteLock
 import java.util.concurrent.locks.ReentrantReadWriteLock
 import java.util.concurrent.locks.ReentrantReadWriteLock.ReadLock
 
-/*
+/**
 Executes given calculation under lock
 Returns result of the calculation
 */
@@ -19,7 +19,7 @@ inline fun <erased T> Lock.withLock(action: ()->T) : T {
     }
 }
 
-/*
+/**
 Executes given calculation under read lock
 Returns result of the calculation
 */
@@ -34,7 +34,7 @@ inline fun <erased T> ReentrantReadWriteLock.read(action: ()->T) : T {
     }
 }
 
-/*
+/**
 Executes given calculation under write lock.
 The method does upgrade from read to write lock if needed
 If such write has been initiated by checking some condition, the condition must be rechecked inside the action to avoid possible races

stdlib/ktSrc/dom/Dom.kt

@@ -267,6 +267,7 @@ inline fun NodeList?.toElementList(): List<Element> {
     }
 }
 
+/** Converts the node list to an XML String */
 fun NodeList?.toXmlString(xmlDeclaration: Boolean = false): String {
     return if (this == null)
         "" else {
@@ -353,7 +354,7 @@ fun Node.ownerDocument(doc: Document? = null): Document {
     }
 }
 
-/*
+/**
 Adds a newly created element which can be configured via a function
 */
 fun Document.addElement(name: String, init: Element.()-> Unit): Element {
@@ -362,7 +363,7 @@ fun Document.addElement(name: String, init: Element.()-> Unit): Element {
     return child
 }
 
-/*
+/**
 Adds a newly created element to an element which has an owner Document which can be configured via a function
 */
 fun Element.addElement(name: String, doc: Document? = null, init: Element.()-> Unit): Element {
@@ -371,7 +372,7 @@ fun Element.addElement(name: String, doc: Document? = null, init: Element.()-> U
     return child
 }
 
-/*
+/**
 Adds a newly created text node to an element which either already has an owner Document or one must be provided as a parameter
 */
 fun Element.addText(text: String?, doc: Document? = null): Element {

stdlib/ktSrc/dom/DomJVM.kt

@@ -18,14 +18,17 @@ import java.lang.Iterable
 import java.util.List
 import java.util.Collection
 
+/** Creates a new document with the given document builder*/
 fun createDocument(builder: DocumentBuilder): Document {
     return builder.newDocument().sure()
 }
 
+/** Creates a new document with an optional DocumentBuilderFactory */
 fun createDocument(builderFactory: DocumentBuilderFactory = DocumentBuilderFactory.newInstance().sure()): Document {
     return createDocument(builderFactory.newDocumentBuilder().sure())
 }
 
+/** Creates a new TrAX transformer */
 fun createTransformer(source: Source? = null, factory: TransformerFactory = TransformerFactory.newInstance().sure()): Transformer {
     val transformer = if (source != null) {
         factory.newTransformer(source)
@@ -35,10 +38,12 @@ fun createTransformer(source: Source? = null, factory: TransformerFactory = Tran
     return transformer.sure()
 }
 
+/** Converts the node to an XML String */
 fun Node.toXmlString(xmlDeclaration: Boolean = this is Document): String {
     return nodeToXmlString(this, xmlDeclaration)
 }
 
+/** Converts the collection of nodes to an XML String */
 fun java.lang.Iterable<Node>.toXmlString(xmlDeclaration: Boolean = false): String {
     // TODO this should work...
     // return this.map<Node,String>{it.toXmlString()}.join("")
@@ -56,6 +61,7 @@ fun Document.toXmlString(xmlDeclaration: Boolean = true): String {
 }
 */
 
+/** Converts the node to an XML String */
 fun nodeToXmlString(node: Node, xmlDeclaration: Boolean): String {
     val transformer = createTransformer()
     transformer.setOutputProperty(OutputKeys.OMIT_XML_DECLARATION, if (xmlDeclaration) "no" else "yes")

stdlib/ktSrc/generated/ArraysFromJavaIterables.kt

@@ -150,23 +150,23 @@ inline fun <T> Array<T>.reverse() : List<T> {
   return answer
 }
 
-/* Copies the collection into the given collection */
+/** Copies the collection into the given collection */
 inline fun <T, C: Collection<T>> Array<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> Array<T>.toLinkedList() : LinkedList<T> = this.to(LinkedList<T>())
 
-/* Converts the collection into a List */
+/** Converts the collection into a List */
 inline fun <T> Array<T>.toList() : List<T> = this.to(ArrayList<T>())
 
-/* Converts the collection into a Set */
+/** Converts the collection into a Set */
 inline fun <T> Array<T>.toSet() : Set<T> = this.to(HashSet<T>())
 
-/* Converts the collection into a SortedSet */
+/** Converts the collection into a SortedSet */
 inline fun <T> Array<T>.toSortedSet() : SortedSet<T> = this.to(TreeSet<T>())
 /**
   TODO figure out necessary variance/generics ninja stuff... :)

stdlib/ktSrc/generated/StandardFromJavaIterables.kt

@@ -150,23 +150,23 @@ inline fun <T> Iterable<T>.reverse() : List<T> {
   return answer
 }
 
-/* Copies the collection into the given collection */
+/** Copies the collection into the given collection */
 inline fun <T, C: Collection<T>> 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> Iterable<T>.toLinkedList() : LinkedList<T> = this.to(LinkedList<T>())
 
-/* Converts the collection into a List */
+/** Converts the collection into a List */
 inline fun <T> Iterable<T>.toList() : List<T> = this.to(ArrayList<T>())
 
-/* Converts the collection into a Set */
+/** Converts the collection into a Set */
 inline fun <T> Iterable<T>.toSet() : Set<T> = this.to(HashSet<T>())
 
-/* Converts the collection into a SortedSet */
+/** Converts the collection into a SortedSet */
 inline fun <T> Iterable<T>.toSortedSet() : SortedSet<T> = this.to(TreeSet<T>())
 /**
   TODO figure out necessary variance/generics ninja stuff... :)