Fix broken links in guide & support links to pseudo-constructors

Author: elizarov

coroutines-guide.md

@@ -343,7 +343,8 @@ main: Now I can quit.
 <!--- TEST -->
 
 As soon as main invokes `job.cancel`, we don't see any output from the other coroutine because it was cancelled. 
-There is also an extension function [cancelAndJoin] that combines [cancel] and [join] invocations.
+There is also a [Job] extension function [cancelAndJoin] 
+that combines [cancel][Job.cancel] and [join][Job.join] invocations.
 
 ### Cancellation is cooperative
 
@@ -458,8 +459,8 @@ fun main(args: Array<String>) = runBlocking<Unit> {
 
 > You can get full code [here](core/kotlinx-coroutines-core/src/test/kotlin/guide/example-cancel-04.kt)
 
-Both [join] and [cancelAndJoin] wait for all the finalization actions to complete, so the example above 
-produces the following output:
+Both [join][Job.join] and [cancelAndJoin] wait for all the finalization actions to complete, 
+so the example above produces the following output:
 
 ```text
 I'm sleeping 0 ...
@@ -1047,7 +1048,7 @@ main: Who has survived request cancellation?
 ### Parental responsibilities 
 
 A parent coroutine always waits for completion of all its children. Parent does not have to explicitly track
-all the children it launches and it does not have to use [join] to wait for them at the end:
+all the children it launches and it does not have to use [Job.join] to wait for them at the end:
 
 ```kotlin
 fun main(args: Array<String>) = runBlocking<Unit> {
@@ -1132,7 +1133,7 @@ and update data, do animations, etc. All of these coroutines must be cancelled w
 to avoid memory leaks. 
 
 We can manage a lifecycle of our coroutines by creating an instance of [Job] that is tied to 
-the lifecycle of our activity. A job instance is created using [`Job()`][Job] factory function
+the lifecycle of our activity. A job instance is created using [Job()] factory function
 as the following example shows. We need to make sure that all the coroutines are started 
 with this job in their context and then a single invocation of [Job.cancel] terminates them all.
 Moreover, [Job.join] waits for all of them to complete, so we can also use [cancelAndJoin] here in
@@ -1373,7 +1374,7 @@ The following example prints the first ten prime numbers,
 running the whole pipeline in the context of the main thread. Since all the coroutines are launched as
 children of the main [runBlocking] coroutine in its [coroutineContext][CoroutineScope.coroutineContext],
 we don't have to keep an explicit list of all the coroutine we have created. 
-We use [CoroutineContext.cancelChildren] extension to cancel all the children coroutines. 
+We use [cancelChildren] extension function to cancel all the children coroutines. 
 
 ```kotlin
 fun main(args: Array<String>) = runBlocking<Unit> {
@@ -1529,7 +1530,7 @@ The channels shown so far had no buffer. Unbuffered channels transfer elements w
 meet each other (aka rendezvous). If send is invoked first, then it is suspended until receive is invoked, 
 if receive is invoked first, it is suspended until send is invoked.
 
-Both [`Channel()`][Channel] factory function and [produce] builder take an optional `capacity` parameter to
+Both [Channel()] factory function and [produce] builder take an optional `capacity` parameter to
 specify _buffer size_. Buffer allows senders to send multiple elements before suspending, 
 similar to the `BlockingQueue` with a specified capacity, which blocks when buffer is full.
 
@@ -1829,7 +1830,7 @@ that is never executed concurrently. In a blocking world you'd typically use `sy
 Coroutine's alternative is called [Mutex]. It has [lock][Mutex.lock] and [unlock][Mutex.unlock] functions to 
 delimit a critical section. The key difference is that `Mutex.lock` is a suspending function. It does not block a thread.
 
-There is also [Mutex.withLock] extension function that conveniently represents 
+There is also [withLock] extension function that conveniently represents 
 `mutex.lock(); try { ... } finally { mutex.unlock() }` pattern: 
 
 ```kotlin
@@ -2292,6 +2293,8 @@ Channel was closed
 [runBlocking]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/run-blocking.html
 [Job]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-job/index.html
 [cancelAndJoin]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/cancel-and-join.html
+[Job.cancel]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-job/cancel.html
+[Job.join]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-job/join.html
 [CancellationException]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-cancellation-exception.html
 [yield]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/yield.html
 [CoroutineScope.isActive]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-scope/is-active.html
@@ -2311,21 +2314,23 @@ Channel was closed
 [Unconfined]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-unconfined/index.html
 [newCoroutineContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/new-coroutine-context.html
 [CoroutineName]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-name/index.html
-[Job.cancel]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-job/cancel.html
-[Job.join]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-job/join.html
+[Job()]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-job.html
+[cancelChildren]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/kotlin.coroutines.experimental.-coroutine-context/cancel-children.html
 [CompletableDeferred]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-completable-deferred/index.html
 [Deferred.onAwait]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-deferred/on-await.html
 <!--- INDEX kotlinx.coroutines.experimental.sync -->
 [Mutex]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.sync/-mutex/index.html
 [Mutex.lock]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.sync/-mutex/lock.html
 [Mutex.unlock]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.sync/-mutex/unlock.html
+[withLock]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.sync/with-lock.html
 <!--- INDEX kotlinx.coroutines.experimental.channels -->
 [Channel]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-channel/index.html
 [SendChannel.send]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-send-channel/send.html
 [ReceiveChannel.receive]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-receive-channel/receive.html
 [SendChannel.close]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-send-channel/close.html
 [produce]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/produce.html
 [consumeEach]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/consume-each.html
+[Channel()]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-channel.html
 [actor]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/actor.html
 [ReceiveChannel.onReceive]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-receive-channel/on-receive.html
 [ReceiveChannel.onReceiveOrNull]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-receive-channel/on-receive-or-null.html

knit/src/Knit.kt

@@ -63,7 +63,7 @@ const val FLEXIBLE_THREAD_PREDICATE = "FLEXIBLE_THREAD"
 const val LINES_START_UNORDERED_PREDICATE = "LINES_START_UNORDERED"
 const val LINES_START_PREDICATE = "LINES_START"
 
-val API_REF_REGEX = Regex("(^|[ \\]])\\[([A-Za-z0-9_.]+)\\]($|[^\\[\\(])")
+val API_REF_REGEX = Regex("(^|[ \\]])\\[([A-Za-z0-9_().]+)\\]($|[^\\[\\(])")
 
 fun main(args: Array<String>) {
     if (args.isEmpty()) {
@@ -424,6 +424,22 @@ val apiIndexCache: MutableMap<ApiIndexKey, Map<String, String>> = HashMap()
 val REF_LINE_REGEX = Regex("<a href=\"([a-z/.\\-]+)\">([a-zA-z.]+)</a>")
 val INDEX_HTML = "/index.html"
 val INDEX_MD = "/index.md"
+val FUNCTIONS_SECTION_HEADER = "### Functions"
+
+val AMBIGUOUS = "#AMBIGUOUS: "
+
+fun HashMap<String,String>.putUnambiguous(key: String, value: String) {
+    val oldValue = this[key]
+    val putVal =
+        if (oldValue != null && oldValue != value) {
+            when {
+                oldValue.contains("[$value]") -> oldValue
+                oldValue.startsWith(AMBIGUOUS) -> "$oldValue; [$value]"
+                else -> "$AMBIGUOUS[$oldValue]; [$value]"
+            }
+        } else value
+    put(key, putVal)
+}
 
 fun loadApiIndex(
     docsRoot: String,
@@ -434,18 +450,28 @@ fun loadApiIndex(
     val fileName = docsRoot + "/" + path + INDEX_MD
     val visited = mutableSetOf<String>()
     val map = HashMap<String,String>()
+    var inFunctionsSection = false
     File(fileName).withLineNumberReader<LineNumberReader>(::LineNumberReader) {
         while (true) {
             val line = readLine() ?: break
+            if (line == FUNCTIONS_SECTION_HEADER) inFunctionsSection = true
             val result = REF_LINE_REGEX.matchEntire(line) ?: continue
-            val refLink = result.groups[1]!!.value
-            if (refLink.startsWith("..")) continue // ignore cross-references
-            val refName = namePrefix + result.groups[2]!!.value
-            map.putIfAbsent(refName, path + "/" + refLink)
-            map.putIfAbsent(pkg + "." + refName, path + "/" + refLink)
-            if (refLink.endsWith(INDEX_HTML)) {
-                if (visited.add(refLink)) {
-                    val path2 = path + "/" + refLink.substring(0, refLink.length - INDEX_HTML.length)
+            val link = result.groups[1]!!.value
+            if (link.startsWith("..")) continue // ignore cross-references
+            val absLink = path + "/" + link
+            var name = result.groups[2]!!.value
+            // a special disambiguation fix for pseudo-constructor functions
+            if (inFunctionsSection && name[0] in 'A'..'Z') name += "()"
+            val refName = namePrefix + name
+            val fqName = pkg + "." + refName
+            // Put short names for extensions on 3rd party classes (prefix is FQname of those classes)
+            if (namePrefix != "" && namePrefix[0] in 'a'..'z') map.putUnambiguous(name, absLink)
+            // Always put fully qualified names
+            map.putUnambiguous(refName, absLink)
+            map.putUnambiguous(fqName, absLink)
+            if (link.endsWith(INDEX_HTML)) {
+                if (visited.add(link)) {
+                    val path2 = path + "/" + link.substring(0, link.length - INDEX_HTML.length)
                     map += loadApiIndex(docsRoot, path2, pkg, refName + ".")
                         ?: throw IllegalArgumentException("Failed to parse ${docsRoot + "/" + path2}")
                 }
@@ -473,6 +499,10 @@ fun processApiIndex(
     while (it.hasNext()) {
         val refName = it.next()
         val refLink = map[refName] ?: continue
+        if (refLink.startsWith(AMBIGUOUS)) {
+            println("WARNING: Ambiguous reference to [$refName]: ${refLink.substring(AMBIGUOUS.length)}")
+            continue
+        }
         indexList += "[$refName]: $siteRoot/$refLink"
         it.remove()
     }