Refactor SinceKotlin support to a more general "platform" mechanism

10 files changed, 57 insertions, 33 deletions

diff --git a/core/src/main/kotlin/Formats/StructuredFormatService.kt b/core/src/main/kotlin/Formats/StructuredFormatService.kt
index 1488a4f9..02ec01b0 100644
--- a/core/src/main/kotlin/Formats/StructuredFormatService.kt
+++ b/core/src/main/kotlin/Formats/StructuredFormatService.kt
@@ -291,7 +291,7 @@ abstract class StructuredOutputBuilder(val to: StringBuilder,
                 }
                 item.appendOverrides()
                 item.appendDeprecation()
-                item.appendSinceKotlin()
+                item.appendPlatforms()
             }
             // All items have exactly the same documentation, so we can use any item to render it
             val item = items.first()
@@ -321,12 +321,6 @@ abstract class StructuredOutputBuilder(val to: StringBuilder,
             }
         }
 
-        private fun DocumentationNode.appendSinceKotlin() {
-            val annotation = sinceKotlin ?: return
-            val value = annotation.detail(NodeKind.Parameter).detail(NodeKind.Value)
-            appendSinceKotlin(value.name)
-        }
-
         private fun DocumentationNode.appendDeprecation() {
             if (deprecation != null) {
                 val deprecationParameter = deprecation!!.details(NodeKind.Parameter).firstOrNull()
@@ -349,6 +343,14 @@ abstract class StructuredOutputBuilder(val to: StringBuilder,
             }
         }
 
+        private fun DocumentationNode.appendPlatforms() {
+            if (platforms.isEmpty()) return
+            appendParagraph {
+                appendStrong { to.append("Platform and version requirements:") }
+                to.append(" " + platforms.joinToString())
+            }
+        }
+
         private fun DocumentationNode.appendDescription() {
             if (content.description != ContentEmpty) {
                 appendContent(content.description)
diff --git a/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt b/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt
index 30c1413d..bcbdf5f4 100644
--- a/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt
+++ b/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt
@@ -62,6 +62,7 @@ class DocumentationBuilder
                     val descriptorDocumentationParser: DescriptorDocumentationParser,
                     val options: DocumentationOptions,
                     val refGraph: NodeReferenceGraph,
+                    val platformNodeRegistry: PlatformNodeRegistry,
                     val logger: DokkaLogger,
                     val linkResolver: DeclarationLinkResolver) {
     val boringBuiltinClasses = setOf(
@@ -199,21 +200,34 @@ class DocumentationBuilder
     fun DocumentationNode.appendAnnotations(annotated: Annotated) {
         annotated.annotations.forEach {
             it.build()?.let { annotationNode ->
-                val refKind = when {
-                    it.isDocumented() ->
-                        when {
-                            annotationNode.isDeprecation() -> RefKind.Deprecation
-                            annotationNode.isSinceKotlin() -> RefKind.SinceKotlin
-                            else -> RefKind.Annotation
-                        }
-                    it.isHiddenInDocumentation() -> RefKind.HiddenAnnotation
-                    else -> return@forEach
+                if (annotationNode.isSinceKotlin()) {
+                    appendSinceKotlin(annotationNode)
                 }
-                append(annotationNode, refKind)
+                else {
+                    val refKind = when {
+                        it.isDocumented() ->
+                            when {
+                                annotationNode.isDeprecation() -> RefKind.Deprecation
+                                else -> RefKind.Annotation
+                            }
+                        it.isHiddenInDocumentation() -> RefKind.HiddenAnnotation
+                        else -> return@forEach
+                    }
+                    append(annotationNode, refKind)
+                }
+
             }
         }
     }
 
+    fun DocumentationNode.appendSinceKotlin(annotation: DocumentationNode) {
+        var kotlinVersion = annotation.detail(NodeKind.Parameter).detail(NodeKind.Value).name
+        if (kotlinVersion.startsWith('\"') && kotlinVersion.endsWith('\"')) {
+            kotlinVersion = kotlinVersion.substring(1..kotlinVersion.length-2)
+        }
+        append(platformNodeRegistry["Kotlin " + kotlinVersion], RefKind.Platform)
+    }
+
     fun DocumentationNode.appendModifiers(descriptor: DeclarationDescriptor) {
         val psi = (descriptor as DeclarationDescriptorWithSource).source.getPsi() as? KtModifierListOwner ?: return
         KtTokens.MODIFIER_KEYWORDS_ARRAY.filter { it !in knownModifiers }.forEach {
diff --git a/core/src/main/kotlin/Model/DocumentationNode.kt b/core/src/main/kotlin/Model/DocumentationNode.kt
index 83897a3f..56c295cd 100644
--- a/core/src/main/kotlin/Model/DocumentationNode.kt
+++ b/core/src/main/kotlin/Model/DocumentationNode.kt
@@ -48,6 +48,7 @@ enum class NodeKind {
     Signature,
 
     ExternalLink,
+    Platform,
 
     AllTypes,
 
@@ -97,8 +98,8 @@ open class DocumentationNode(val name: String,
         get() = references(RefKind.Annotation).map { it.to }
     val deprecation: DocumentationNode?
         get() = references(RefKind.Deprecation).singleOrNull()?.to
-    val sinceKotlin: DocumentationNode?
-        get() = references(RefKind.SinceKotlin).singleOrNull()?.to
+    val platforms: List<String>
+        get() = references(RefKind.Platform).map { it.to.name }
 
     // TODO: Should we allow node mutation? Model merge will copy by ref, so references are transparent, which could nice
     fun addReferenceTo(to: DocumentationNode, kind: RefKind) {
diff --git a/core/src/main/kotlin/Model/DocumentationReference.kt b/core/src/main/kotlin/Model/DocumentationReference.kt
index 8263cd6a..4f28d7c3 100644
--- a/core/src/main/kotlin/Model/DocumentationReference.kt
+++ b/core/src/main/kotlin/Model/DocumentationReference.kt
@@ -19,7 +19,7 @@ enum class RefKind {
     HiddenAnnotation,
     Deprecation,
     TopLevelPage,
-    SinceKotlin
+    Platform
 }
 
 data class DocumentationReference(val from: DocumentationNode, val to: DocumentationNode, val kind: RefKind) {
@@ -71,3 +71,14 @@ class NodeReferenceGraph
         references.forEach { it.resolve() }
     }
 }
+
+@Singleton
+class PlatformNodeRegistry {
+    private val platformNodes = hashMapOf<String, DocumentationNode>()
+
+    operator fun get(platform: String): DocumentationNode {
+        return platformNodes.getOrPut(platform) {
+            DocumentationNode(platform, Content.Empty, NodeKind.Platform)
+        }
+    }
+}
diff --git a/core/src/test/kotlin/model/ClassTest.kt b/core/src/test/kotlin/model/ClassTest.kt
index b6ac7126..fb225728 100644
--- a/core/src/test/kotlin/model/ClassTest.kt
+++ b/core/src/test/kotlin/model/ClassTest.kt
@@ -3,10 +3,9 @@ package org.jetbrains.dokka.tests
 import org.jetbrains.dokka.Content
 import org.jetbrains.dokka.NodeKind
 import org.jetbrains.dokka.RefKind
-import org.junit.Test
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertTrue
-import kotlin.test.assertNotNull
+import org.junit.Test
 
 class ClassTest {
     @Test fun emptyClass() {
@@ -277,7 +276,7 @@ class ClassTest {
     @Test fun sinceKotlin() {
         verifyModel("testdata/classes/sinceKotlin.kt") { model ->
             with(model.members.single().members.single()) {
-                assertNotNull(sinceKotlin)
+                assertEquals(listOf("Kotlin 1.1"), platforms)
             }
         }
     }
diff --git a/core/src/test/kotlin/model/FunctionTest.kt b/core/src/test/kotlin/model/FunctionTest.kt
index 8cf6b14a..ddd33941 100644
--- a/core/src/test/kotlin/model/FunctionTest.kt
+++ b/core/src/test/kotlin/model/FunctionTest.kt
@@ -2,10 +2,9 @@ package org.jetbrains.dokka.tests
 
 import org.jetbrains.dokka.Content
 import org.jetbrains.dokka.NodeKind
-import org.junit.Test
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertTrue
-import kotlin.test.assertNotNull
+import org.junit.Test
 
 class FunctionTest {
     @Test fun function() {
@@ -229,7 +228,7 @@ Documentation""", content.description.toTestString())
     @Test fun sinceKotlin() {
         verifyModel("testdata/functions/sinceKotlin.kt") { model ->
             with(model.members.single().members.single()) {
-                assertNotNull(sinceKotlin)
+                assertEquals(listOf("Kotlin 1.1"), platforms)
             }
         }
     }
diff --git a/core/src/test/kotlin/model/PropertyTest.kt b/core/src/test/kotlin/model/PropertyTest.kt
index 1dbb102a..0ee0e0f5 100644
--- a/core/src/test/kotlin/model/PropertyTest.kt
+++ b/core/src/test/kotlin/model/PropertyTest.kt
@@ -3,10 +3,9 @@ package org.jetbrains.dokka.tests
 import org.jetbrains.dokka.Content
 import org.jetbrains.dokka.NodeKind
 import org.jetbrains.dokka.RefKind
-import org.junit.Test
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertTrue
-import kotlin.test.assertNotNull
+import org.junit.Test
 
 class PropertyTest {
     @Test fun valueProperty() {
@@ -105,7 +104,7 @@ class PropertyTest {
     @Test fun sinceKotlin() {
         verifyModel("testdata/properties/sinceKotlin.kt") { model ->
             with(model.members.single().members.single()) {
-                assertNotNull(sinceKotlin)
+                assertEquals(listOf("Kotlin 1.1"), platforms)
             }
         }
     }
diff --git a/core/src/test/kotlin/model/TypeAliasTest.kt b/core/src/test/kotlin/model/TypeAliasTest.kt
index dbb15be4..c653ac83 100644
--- a/core/src/test/kotlin/model/TypeAliasTest.kt
+++ b/core/src/test/kotlin/model/TypeAliasTest.kt
@@ -4,7 +4,6 @@ import junit.framework.TestCase.assertEquals
 import org.jetbrains.dokka.Content
 import org.jetbrains.dokka.NodeKind
 import org.junit.Test
-import kotlin.test.assertNotNull
 
 class TypeAliasTest {
     @Test
@@ -126,7 +125,7 @@ class TypeAliasTest {
     fun sinceKotlin() {
         verifyModel("testdata/typealias/sinceKotlin.kt") { model ->
             with(model.members.single().members.single()) {
-                assertNotNull(sinceKotlin)
+                assertEquals(listOf("Kotlin 1.1"), platforms)
             }
         }
     }
diff --git a/core/testdata/format/sinceKotlin.html b/core/testdata/format/sinceKotlin.html
index 6f6a6896..eef5ca66 100644
--- a/core/testdata/format/sinceKotlin.html
+++ b/core/testdata/format/sinceKotlin.html
@@ -8,7 +8,7 @@
 <br/>
 <h1>Since1.1</h1>
 <code><span class="keyword">class </span><span class="identifier">Since1.1</span></code>
-<p>Available since Kotlin: <code>"1.1"</code></p>
+<p><strong>Platform and version requirements:</strong> Kotlin 1.1</p>
 <p>Useful</p>
 <h3>Constructors</h3>
 <table>
diff --git a/core/testdata/format/sinceKotlin.md b/core/testdata/format/sinceKotlin.md
index cef04e74..a1abe5fd 100644
--- a/core/testdata/format/sinceKotlin.md
+++ b/core/testdata/format/sinceKotlin.md
@@ -4,7 +4,7 @@
 
 `class Since1.1`
 
-Available since Kotlin: `"1.1"`
+**Platform and version requirements:** Kotlin 1.1
 
 Useful