diff options
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 7896bcd8..1488a4f9 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 afb95fe6..30c1413d 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 def0f626..83897a3f 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 0165b567..8263cd6a 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 108c5bbf..61eab562 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 4b4eff59..1816c075 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 f870d898..4dd01a20 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 d50a3624..b6ac7126 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 4cced562..8cf6b14a 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 cdf44c03..1dbb102a 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 812fd9dc..dbb15be4 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 00000000..1025cf0d --- /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 00000000..6f6a6896 --- /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> / <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-"><init></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 00000000..1025cf0d --- /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 00000000..cef04e74 --- /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 + +| [<init>](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 00000000..5e9250f8 --- /dev/null +++ b/core/testdata/format/sinceKotlin.package.md @@ -0,0 +1,8 @@ +[test](test/index) + +## Package <root> + +### 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 00000000..cdcd3357 --- /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 00000000..e96f2349 --- /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 00000000..5b76f63a --- /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 |