Dokka now can detect and recognize SinceKotlin

19 files changed, 156 insertions, 8 deletions

diff --git a/core/src/main/kotlin/Formats/StructuredFormatService.kt b/core/src/main/kotlin/Formats/StructuredFormatService.kt
index 7896bcd80..1488a4f9d 100644
--- a/core/src/main/kotlin/Formats/StructuredFormatService.kt
+++ b/core/src/main/kotlin/Formats/StructuredFormatService.kt
@@ -59,6 +59,13 @@ abstract class StructuredOutputBuilder(val to: StringBuilder,
 
     abstract fun appendText(text: String)
 
+    open fun appendSinceKotlin(version: String) {
+        appendParagraph {
+            appendText("Available since Kotlin: ")
+            appendCode { appendText(version) }
+        }
+    }
+
     open fun appendSymbol(text: String) {
         appendText(text)
     }
@@ -284,12 +291,14 @@ abstract class StructuredOutputBuilder(val to: StringBuilder,
                 }
                 item.appendOverrides()
                 item.appendDeprecation()
+                item.appendSinceKotlin()
             }
             // All items have exactly the same documentation, so we can use any item to render it
             val item = items.first()
             item.details(NodeKind.OverloadGroupNote).forEach {
                 appendContent(it.content)
             }
+
             appendContent(item.content.summary)
             item.appendDescription()
         }
@@ -312,6 +321,12 @@ 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()
diff --git a/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt b/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt
index afb95fe60..30c1413dd 100644
--- a/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt
+++ b/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt
@@ -200,8 +200,12 @@ class DocumentationBuilder
         annotated.annotations.forEach {
             it.build()?.let { annotationNode ->
                 val refKind = when {
-                    it.isDocumented() && annotationNode.isDeprecation() -> RefKind.Deprecation
-                    it.isDocumented() -> RefKind.Annotation
+                    it.isDocumented() ->
+                        when {
+                            annotationNode.isDeprecation() -> RefKind.Deprecation
+                            annotationNode.isSinceKotlin() -> RefKind.SinceKotlin
+                            else -> RefKind.Annotation
+                        }
                     it.isHiddenInDocumentation() -> RefKind.HiddenAnnotation
                     else -> return@forEach
                 }
@@ -221,6 +225,8 @@ class DocumentationBuilder
 
     fun DocumentationNode.isDeprecation() = name == "Deprecated" || name == "deprecated"
 
+    fun DocumentationNode.isSinceKotlin() = name == "SinceKotlin" && kind == NodeKind.Annotation
+
     fun DocumentationNode.appendSourceLink(sourceElement: SourceElement) {
         appendSourceLink(sourceElement.getPsi(), options.sourceLinks)
     }
diff --git a/core/src/main/kotlin/Model/DocumentationNode.kt b/core/src/main/kotlin/Model/DocumentationNode.kt
index def0f6262..83897a3fc 100644
--- a/core/src/main/kotlin/Model/DocumentationNode.kt
+++ b/core/src/main/kotlin/Model/DocumentationNode.kt
@@ -97,6 +97,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
 
     // 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 0165b5679..8263cd6ad 100644
--- a/core/src/main/kotlin/Model/DocumentationReference.kt
+++ b/core/src/main/kotlin/Model/DocumentationReference.kt
@@ -18,7 +18,8 @@ enum class RefKind {
     Annotation,
     HiddenAnnotation,
     Deprecation,
-    TopLevelPage
+    TopLevelPage,
+    SinceKotlin
 }
 
 data class DocumentationReference(val from: DocumentationNode, val to: DocumentationNode, val kind: RefKind) {
diff --git a/core/src/test/kotlin/TestAPI.kt b/core/src/test/kotlin/TestAPI.kt
index 108c5bbf6..61eab562c 100644
--- a/core/src/test/kotlin/TestAPI.kt
+++ b/core/src/test/kotlin/TestAPI.kt
@@ -141,7 +141,12 @@ private fun verifyModelOutput(it: DocumentationModule,
     outputGenerator(it, output)
     val ext = outputExtension.removePrefix(".")
     val path = sourcePath
-    val expectedOutput = File(path.replaceAfterLast(".", ext, path + "." + ext)).readText()
+    val expectedFileContent = File(path.replaceAfterLast(".", ext, path + "." + ext)).readText()
+    val expectedOutput =
+            if (ext.equals("html", true))
+                expectedFileContent.lines().joinToString(separator = "\n", transform = String::trim)
+            else
+                expectedFileContent
     assertEqualsIgnoringSeparators(expectedOutput, output.toString())
 }
 
diff --git a/core/src/test/kotlin/format/HtmlFormatTest.kt b/core/src/test/kotlin/format/HtmlFormatTest.kt
index 4b4eff598..1816c0756 100644
--- a/core/src/test/kotlin/format/HtmlFormatTest.kt
+++ b/core/src/test/kotlin/format/HtmlFormatTest.kt
@@ -138,6 +138,10 @@ class HtmlFormatTest {
         verifyHtmlNode("functionalTypeWithNamedParameters")
     }
 
+    @Test fun sinceKotlin() {
+        verifyHtmlNode("sinceKotlin")
+    }
+
     private fun verifyHtmlNode(fileName: String, withKotlinRuntime: Boolean = false) {
         verifyHtmlNodes(fileName, withKotlinRuntime) { model -> model.members.single().members }
     }
diff --git a/core/src/test/kotlin/format/MarkdownFormatTest.kt b/core/src/test/kotlin/format/MarkdownFormatTest.kt
index f870d898e..4dd01a20d 100644
--- a/core/src/test/kotlin/format/MarkdownFormatTest.kt
+++ b/core/src/test/kotlin/format/MarkdownFormatTest.kt
@@ -4,7 +4,6 @@ import org.jetbrains.dokka.DocumentationModule
 import org.jetbrains.dokka.DocumentationNode
 import org.jetbrains.dokka.KotlinLanguageService
 import org.jetbrains.dokka.MarkdownFormatService
-import org.junit.Ignore
 import org.junit.Test
 
 class MarkdownFormatTest {
@@ -241,6 +240,11 @@ class MarkdownFormatTest {
         verifyMarkdownPackage("suspendParam")
     }
 
+    @Test fun sinceKotlin() {
+        verifyMarkdownNode("sinceKotlin")
+        verifyMarkdownPackage("sinceKotlin")
+    }
+
     private fun verifyMarkdownPackage(fileName: String, withKotlinRuntime: Boolean = false) {
         verifyOutput("testdata/format/$fileName.kt", ".package.md", withKotlinRuntime = withKotlinRuntime) { model, output ->
             markdownService.createOutputBuilder(output, tempLocation).appendNodes(model.members)
diff --git a/core/src/test/kotlin/model/ClassTest.kt b/core/src/test/kotlin/model/ClassTest.kt
index d50a3624b..b6ac7126f 100644
--- a/core/src/test/kotlin/model/ClassTest.kt
+++ b/core/src/test/kotlin/model/ClassTest.kt
@@ -6,8 +6,9 @@ import org.jetbrains.dokka.RefKind
 import org.junit.Test
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertTrue
+import kotlin.test.assertNotNull
 
-public class ClassTest {
+class ClassTest {
     @Test fun emptyClass() {
         verifyModel("testdata/classes/emptyClass.kt") { model ->
             with(model.members.single().members.single()) {
@@ -272,4 +273,12 @@ public class ClassTest {
             }
         }
     }
+
+    @Test fun sinceKotlin() {
+        verifyModel("testdata/classes/sinceKotlin.kt") { model ->
+            with(model.members.single().members.single()) {
+                assertNotNull(sinceKotlin)
+            }
+        }
+    }
 }
diff --git a/core/src/test/kotlin/model/FunctionTest.kt b/core/src/test/kotlin/model/FunctionTest.kt
index 4cced562a..8cf6b14a8 100644
--- a/core/src/test/kotlin/model/FunctionTest.kt
+++ b/core/src/test/kotlin/model/FunctionTest.kt
@@ -5,8 +5,9 @@ import org.jetbrains.dokka.NodeKind
 import org.junit.Test
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertTrue
+import kotlin.test.assertNotNull
 
-public class FunctionTest {
+class FunctionTest {
     @Test fun function() {
         verifyModel("testdata/functions/function.kt") { model ->
             with(model.members.single().members.single()) {
@@ -224,4 +225,12 @@ Documentation""", content.description.toTestString())
             }
         }
     }
+
+    @Test fun sinceKotlin() {
+        verifyModel("testdata/functions/sinceKotlin.kt") { model ->
+            with(model.members.single().members.single()) {
+                assertNotNull(sinceKotlin)
+            }
+        }
+    }
 }
diff --git a/core/src/test/kotlin/model/PropertyTest.kt b/core/src/test/kotlin/model/PropertyTest.kt
index cdf44c038..1dbb102a5 100644
--- a/core/src/test/kotlin/model/PropertyTest.kt
+++ b/core/src/test/kotlin/model/PropertyTest.kt
@@ -6,8 +6,9 @@ import org.jetbrains.dokka.RefKind
 import org.junit.Test
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertTrue
+import kotlin.test.assertNotNull
 
-public class PropertyTest {
+class PropertyTest {
     @Test fun valueProperty() {
         verifyModel("testdata/properties/valueProperty.kt") { model ->
             with(model.members.single().members.single()) {
@@ -100,4 +101,12 @@ public class PropertyTest {
             }
         }
     }
+
+    @Test fun sinceKotlin() {
+        verifyModel("testdata/properties/sinceKotlin.kt") { model ->
+            with(model.members.single().members.single()) {
+                assertNotNull(sinceKotlin)
+            }
+        }
+    }
 }
diff --git a/core/src/test/kotlin/model/TypeAliasTest.kt b/core/src/test/kotlin/model/TypeAliasTest.kt
index 812fd9dc7..dbb15be4b 100644
--- a/core/src/test/kotlin/model/TypeAliasTest.kt
+++ b/core/src/test/kotlin/model/TypeAliasTest.kt
@@ -4,6 +4,7 @@ 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
@@ -120,4 +121,13 @@ class TypeAliasTest {
             }
         }
     }
+
+    @Test
+    fun sinceKotlin() {
+        verifyModel("testdata/typealias/sinceKotlin.kt") { model ->
+            with(model.members.single().members.single()) {
+                assertNotNull(sinceKotlin)
+            }
+        }
+    }
 }
\ No newline at end of file
diff --git a/core/testdata/classes/sinceKotlin.kt b/core/testdata/classes/sinceKotlin.kt
new file mode 100644
index 000000000..1025cf0d3
--- /dev/null
+++ b/core/testdata/classes/sinceKotlin.kt
@@ -0,0 +1,5 @@
+/**
+ * Useful
+ */
+@SinceKotlin("1.1")
+class `Since1.1`
\ No newline at end of file
diff --git a/core/testdata/format/sinceKotlin.html b/core/testdata/format/sinceKotlin.html
new file mode 100644
index 000000000..6f6a68968
--- /dev/null
+++ b/core/testdata/format/sinceKotlin.html
@@ -0,0 +1,27 @@
+<HTML>
+<HEAD>
+    <meta charset="UTF-8">
+    <title>Since1.1 - test</title>
+</HEAD>
+<BODY>
+<a href="test/index">test</a>&nbsp;/&nbsp;<a href="test/-since1.1/index">Since1.1</a><br/>
+<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>Useful</p>
+<h3>Constructors</h3>
+<table>
+    <tbody>
+    <tr>
+        <td>
+            <a href="test/-since1.1/-init-">&lt;init&gt;</a></td>
+        <td>
+            <code><span class="identifier">Since1.1</span><span class="symbol">(</span><span class="symbol">)</span></code>
+            <p>Useful</p>
+        </td>
+    </tr>
+    </tbody>
+</table>
+</BODY>
+</HTML>
diff --git a/core/testdata/format/sinceKotlin.kt b/core/testdata/format/sinceKotlin.kt
new file mode 100644
index 000000000..1025cf0d3
--- /dev/null
+++ b/core/testdata/format/sinceKotlin.kt
@@ -0,0 +1,5 @@
+/**
+ * Useful
+ */
+@SinceKotlin("1.1")
+class `Since1.1`
\ No newline at end of file
diff --git a/core/testdata/format/sinceKotlin.md b/core/testdata/format/sinceKotlin.md
new file mode 100644
index 000000000..cef04e74b
--- /dev/null
+++ b/core/testdata/format/sinceKotlin.md
@@ -0,0 +1,14 @@
+[test](test/index) / [Since1.1](test/-since1.1/index)
+
+# Since1.1
+
+`class Since1.1`
+
+Available since Kotlin: `"1.1"`
+
+Useful
+
+### Constructors
+
+| [&lt;init&gt;](test/-since1.1/-init-) | `Since1.1()`<br>Useful |
+
diff --git a/core/testdata/format/sinceKotlin.package.md b/core/testdata/format/sinceKotlin.package.md
new file mode 100644
index 000000000..5e9250f8d
--- /dev/null
+++ b/core/testdata/format/sinceKotlin.package.md
@@ -0,0 +1,8 @@
+[test](test/index)
+
+## Package &lt;root&gt;
+
+### Types
+
+| [Since1.1](test/-since1.1/index) | `class Since1.1`<br>Useful |
+
diff --git a/core/testdata/functions/sinceKotlin.kt b/core/testdata/functions/sinceKotlin.kt
new file mode 100644
index 000000000..cdcd33570
--- /dev/null
+++ b/core/testdata/functions/sinceKotlin.kt
@@ -0,0 +1,5 @@
+/**
+ * Quite useful [String]
+ */
+@SinceKotlin("1.1")
+fun `availableSince1.1`(): String = "1.1 rulezz"
\ No newline at end of file
diff --git a/core/testdata/properties/sinceKotlin.kt b/core/testdata/properties/sinceKotlin.kt
new file mode 100644
index 000000000..e96f2349f
--- /dev/null
+++ b/core/testdata/properties/sinceKotlin.kt
@@ -0,0 +1,5 @@
+/**
+ * Quite useful [String]
+ */
+@SinceKotlin("1.1")
+val `availableSince1.1`: String = "1.1 rulezz"
\ No newline at end of file
diff --git a/core/testdata/typealias/sinceKotlin.kt b/core/testdata/typealias/sinceKotlin.kt
new file mode 100644
index 000000000..5b76f63ad
--- /dev/null
+++ b/core/testdata/typealias/sinceKotlin.kt
@@ -0,0 +1,5 @@
+/**
+ * Documentation
+ */
+@SinceKotlin("1.1")
+typealias `Since 1.1` = String
\ No newline at end of file