diff options
11 files changed, 116 insertions, 71 deletions
diff --git a/core/src/main/kotlin/model/doc/DocTag.kt b/core/src/main/kotlin/model/doc/DocTag.kt index 812acd62..902dedec 100644 --- a/core/src/main/kotlin/model/doc/DocTag.kt +++ b/core/src/main/kotlin/model/doc/DocTag.kt @@ -1,11 +1,12 @@ package org.jetbrains.dokka.model.doc import org.jetbrains.dokka.links.DRI +import org.jetbrains.dokka.model.WithChildren sealed class DocTag( - val children: List<DocTag>, + override val children: List<DocTag>, val params: Map<String, String> -) { +) : WithChildren { override fun equals(other: Any?): Boolean = ( other != null && diff --git a/core/src/main/kotlin/model/doc/DocumentationNode.kt b/core/src/main/kotlin/model/doc/DocumentationNode.kt index a143a941..cfac210a 100644 --- a/core/src/main/kotlin/model/doc/DocumentationNode.kt +++ b/core/src/main/kotlin/model/doc/DocumentationNode.kt @@ -1,3 +1,5 @@ package org.jetbrains.dokka.model.doc -data class DocumentationNode(val children: List<TagWrapper>)
\ No newline at end of file +import org.jetbrains.dokka.model.WithChildren + +data class DocumentationNode(override val children: List<TagWrapper>): WithChildren
\ No newline at end of file diff --git a/core/src/main/kotlin/model/doc/TagWrapper.kt b/core/src/main/kotlin/model/doc/TagWrapper.kt index af45e7eb..458203b0 100644 --- a/core/src/main/kotlin/model/doc/TagWrapper.kt +++ b/core/src/main/kotlin/model/doc/TagWrapper.kt @@ -1,8 +1,12 @@ package org.jetbrains.dokka.model.doc import org.jetbrains.dokka.links.DRI +import org.jetbrains.dokka.model.WithChildren -sealed class TagWrapper(val root: DocTag) { +sealed class TagWrapper(val root: DocTag) : WithChildren { + + override val children: List<DocTag> + get() = root.children override fun equals(other: Any?): Boolean = ( diff --git a/core/src/main/kotlin/model/documentableUtils.kt b/core/src/main/kotlin/model/documentableUtils.kt index 7057a62c..f49c0967 100644 --- a/core/src/main/kotlin/model/documentableUtils.kt +++ b/core/src/main/kotlin/model/documentableUtils.kt @@ -19,4 +19,14 @@ fun DTypeParameter.filter(filteredSet: Set<DokkaSourceSet>) = intersection, extra ) - }
\ No newline at end of file + } + +interface WithChildren { + val children: List<*> +} + +inline fun <reified T> WithChildren.firstChildOfType() = + children.filterIsInstance<T>().firstOrNull() + +inline fun <reified T> WithChildren.firstChildOfType(predicate: (T) -> Boolean) = + children.filterIsInstance<T>().firstOrNull(predicate)
\ No newline at end of file diff --git a/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt b/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt index 8588534b..7c797233 100644 --- a/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt +++ b/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt @@ -43,7 +43,7 @@ class DefaultPsiToDocumentableTranslator( override fun invoke(sourceSet: DokkaSourceSet, context: DokkaContext): DModule { - fun isFileInSourceRoots(file: File): Boolean { + fun isFileInSourceRoots(file: File) : Boolean { return sourceSet.sourceRoots.any { root -> file.path.startsWith(File(root.path).absolutePath) } } @@ -256,7 +256,7 @@ class DefaultPsiToDocumentableTranslator( inheritedFrom: DRI? = null ): DFunction { val dri = DRI.from(psi) - val docs = javadocParser.parseDocumentation(psi).toSourceSetDependent() + val docs = javadocParser.parseDocumentation(psi) return DFunction( dri, if (isConstructor) "<init>" else psi.name, @@ -265,13 +265,17 @@ class DefaultPsiToDocumentableTranslator( DParameter( dri.copy(target = dri.target.nextTarget()), psiParameter.name, - DocumentationNode(docs.entries.mapNotNull { it.value.children.filterIsInstance<Param>().firstOrNull { it.root.children.firstIsInstanceOrNull<DocumentationLink>()?.children?.firstIsInstanceOrNull<Text>()?.body == psiParameter.name } }).toSourceSetDependent(), + DocumentationNode( + listOfNotNull(docs.firstChildOfType<Param> { + it.firstChildOfType<DocumentationLink>() + ?.firstChildOfType<Text>()?.body == psiParameter.name + })).toSourceSetDependent(), null, getBound(psiParameter.type), setOf(sourceSetData) ) }, - docs, + docs.toSourceSetDependent(), null, PsiDocumentableSource(psi).toSourceSetDependent(), psi.getVisibility().toSourceSetDependent(), @@ -301,7 +305,6 @@ class DefaultPsiToDocumentableTranslator( ExtraModifiers.JavaOnlyModifiers.Transitive.takeIf { hasModifier(JvmModifier.TRANSITIVE) } ).toSet() - private fun Set<ExtraModifiers>.toListOfAnnotations() = map { if (it !is ExtraModifiers.JavaOnlyModifiers.Static) Annotations.Annotation(DRI("kotlin.jvm", it.name.toLowerCase().capitalize()), emptyMap()) @@ -394,7 +397,7 @@ class DefaultPsiToDocumentableTranslator( val dri = DRI.from(psi) return DProperty( dri, - psi.name!!, // TODO: Investigate if this is indeed nullable + psi.name, javadocParser.parseDocumentation(psi).toSourceSetDependent(), null, PsiDocumentableSource(psi).toSourceSetDependent(), diff --git a/plugins/base/src/test/kotlin/model/JavaTest.kt b/plugins/base/src/test/kotlin/model/JavaTest.kt index aefcc642..bd7e3b55 100644 --- a/plugins/base/src/test/kotlin/model/JavaTest.kt +++ b/plugins/base/src/test/kotlin/model/JavaTest.kt @@ -6,13 +6,10 @@ import org.jetbrains.dokka.links.sureClassNames import org.jetbrains.dokka.model.* import org.jetbrains.dokka.model.doc.Param import org.jetbrains.dokka.model.doc.Text -import org.jetbrains.dokka.pages.dfs -import org.jetbrains.kotlin.utils.addToStdlib.firstIsInstanceOrNull import org.junit.jupiter.api.Assertions.assertTrue import org.junit.jupiter.api.Test import utils.AbstractModelTest import utils.assertNotNull -import utils.docs import utils.name class JavaTest : AbstractModelTest("/src/main/kotlin/java/Test.java", "java") { @@ -37,7 +34,7 @@ class JavaTest : AbstractModelTest("/src/main/kotlin/java/Test.java", "java") { with((this / "fn").cast<DFunction>()) { name equals "fn" val params = parameters.map { it.documentation.values.first().children.first() as Param } - params.mapNotNull { it.root.children.firstIsInstanceOrNull<Text>()?.body } equals listOf("is String parameter", "is int parameter") + params.mapNotNull { it.firstChildOfType<Text>()?.body } equals listOf("is String parameter", "is int parameter") } } } diff --git a/plugins/javadoc/src/main/kotlin/javadoc/JavadocPageCreator.kt b/plugins/javadoc/src/main/kotlin/javadoc/JavadocPageCreator.kt index 6cf34ed1..3074a760 100644 --- a/plugins/javadoc/src/main/kotlin/javadoc/JavadocPageCreator.kt +++ b/plugins/javadoc/src/main/kotlin/javadoc/JavadocPageCreator.kt @@ -9,21 +9,19 @@ import org.jetbrains.dokka.base.transformers.pages.comments.CommentsToContentCon import org.jetbrains.dokka.base.transformers.pages.comments.DocTagToContentConverter import org.jetbrains.dokka.model.* import org.jetbrains.dokka.model.doc.Description -import org.jetbrains.dokka.model.doc.Param import org.jetbrains.dokka.model.doc.TagWrapper -import org.jetbrains.dokka.model.doc.Text import org.jetbrains.dokka.model.properties.PropertyContainer import org.jetbrains.dokka.model.properties.WithExtraProperties import org.jetbrains.dokka.pages.ContentKind import org.jetbrains.dokka.pages.ContentNode +import org.jetbrains.dokka.pages.ContentText import org.jetbrains.dokka.pages.DCI import org.jetbrains.dokka.utilities.DokkaLogger -import org.jetbrains.kotlin.utils.addToStdlib.firstIsInstanceOrNull import org.jetbrains.kotlin.utils.addToStdlib.safeAs open class JavadocPageCreator( commentsToContentConverter: CommentsToContentConverter, - val signatureProvider: SignatureProvider, + private val signatureProvider: SignatureProvider, val logger: DokkaLogger ) { @@ -41,81 +39,63 @@ open class JavadocPageCreator( ) fun pageForClasslike(c: DClasslike): JavadocClasslikePageNode? = - c.sourceSets.firstOrNull { it.analysisPlatform == Platform.jvm }?.let { jvm -> + c.mostTopSourceSet?.let { jvm -> JavadocClasslikePageNode( name = c.name.orEmpty(), content = contentForClasslike(c), dri = setOf(c.dri), modifiers = listOfNotNull(c.visibility[jvm]?.name), signature = signatureProvider.signature(c).jvmSignature(), - description = c.description(jvm), + description = c.descriptionToContentNodes(), constructors = c.safeAs<WithConstructors>()?.constructors?.map { it.toJavadocFunction(jvm) }.orEmpty(), methods = c.functions.map { it.toJavadocFunction(jvm) }, - entries = c.safeAs<DEnum>()?.entries?.map { - JavadocEntryNode( - signatureProvider.signature(it).jvmSignature(), - it.description(jvm) - ) - }.orEmpty(), + entries = c.safeAs<DEnum>()?.entries?.map { JavadocEntryNode(signatureProvider.signature(it).jvmSignature(), it.descriptionToContentNodes(jvm)) }.orEmpty(), classlikes = c.classlikes.mapNotNull { pageForClasslike(it) }, - properties = c.properties.map { - JavadocPropertyNode( - signatureProvider.signature(it).jvmSignature(), - TextNode(it.description(jvm), setOf(jvm)) - ) - }, + properties = c.properties.map { JavadocPropertyNode(signatureProvider.signature(it).jvmSignature(), it.descriptionToContentNodes(jvm)) }, documentable = c, extras = c.safeAs<WithExtraProperties<Documentable>>()?.extra ?: PropertyContainer.empty() ) } - fun contentForModule(m: DModule): JavadocContentNode = + private fun contentForModule(m: DModule): JavadocContentNode = JavadocContentGroup( setOf(m.dri), JavadocContentKind.OverviewSummary, - m.sourceSets.filter { it.analysisPlatform == Platform.jvm }.toSet() + m.jvmSource.toSet() ) { - title(m.name, "0.0.1", dri = setOf(m.dri), kind = ContentKind.Main) + title(m.name, m.brief(),"0.0.1", dri = setOf(m.dri), kind = ContentKind.Main) list("Packages", "Package", setOf(m.dri), ContentKind.Packages, m.packages.sortedBy { it.name }.map { p -> - val description = p.documentation.entries.find { (k, _) -> k.analysisPlatform == Platform.jvm }?.value?.let { - it.children.firstIsInstanceOrNull<Description>()?.let { description -> - DocTagToContentConverter.buildContent( - description.root, - DCI(setOf(p.dri), JavadocContentKind.OverviewSummary), - sourceSets - ) - } - }.orEmpty() RowJavadocListEntry( LinkJavadocListEntry(p.name, setOf(p.dri), JavadocContentKind.PackageSummary, sourceSets), - description + p.brief() ) }) } - fun contentForPackage(p: DPackage): JavadocContentNode = + private fun contentForPackage(p: DPackage): JavadocContentNode = JavadocContentGroup( setOf(p.dri), JavadocContentKind.PackageSummary, - p.sourceSets.filter { it.analysisPlatform == Platform.jvm }.toSet() + p.jvmSource.toSet() ) { - title(p.name, "0.0.1", dri = setOf(p.dri), kind = ContentKind.Packages) + title(p.name, p.brief(),"0.0.1", dri = setOf(p.dri), kind = ContentKind.Packages) list("Packages", "Package", setOf(p.dri), ContentKind.Packages, p.classlikes.sortedBy { it.name }.map { c -> RowJavadocListEntry( LinkJavadocListEntry(c.name.orEmpty(), setOf(c.dri), JavadocContentKind.Class, sourceSets), - listOf(signatureProvider.signature(c).jvmSignature()) + c.brief() ) }) } - fun contentForClasslike(c: DClasslike): JavadocContentNode = + private fun contentForClasslike(c: DClasslike): JavadocContentNode = JavadocContentGroup( setOf(c.dri), JavadocContentKind.Class, - c.sourceSets.filter { it.analysisPlatform == Platform.jvm }.toSet() + c.jvmSource.toSet() ) { title( c.name.orEmpty(), + c.brief(), "0.0.1", parent = c.dri.packageName, dri = setOf(c.dri), @@ -150,24 +130,51 @@ open class JavadocPageCreator( private fun DFunction.toJavadocFunction(sourceSetData: DokkaSourceSet) = JavadocFunctionNode( name = name, signature = signatureProvider.signature(this).jvmSignature(), - brief = TextNode(description(sourceSetData), setOf(sourceSetData)), + brief = brief(sourceSetData), parameters = parameters.map { JavadocParameterNode( name = it.name.orEmpty(), type = signatureForProjection(it.type), - description = TextNode(it.findNodeInDocumentation<Param>(sourceSetData), setOf(sourceSetData)) + description = it.brief() ) }, extras = extra ) - fun List<ContentNode>.jvmSignature(): ContentNode = - first { it.sourceSets.any { it.analysisPlatform == Platform.jvm } } + // THIS MUST BE DISCUSSED + private val Documentable.jvmSource + get() = sourceSets.filter { it.analysisPlatform == Platform.jvm } - private fun Documentable.description(sourceSetData: DokkaSourceSet): String = - findNodeInDocumentation<Description>(sourceSetData) + private val Documentable.mostTopSourceSet + get() = jvmSource.let { sources -> + sources.firstOrNull { it != expectPresentInSet } ?: sources.firstOrNull() + } + + private val firstSentenceRegex = Regex("^((?:[^.?!]|[.!?](?!\\s))*[.!?])") - private inline fun <reified T : TagWrapper> Documentable.findNodeInDocumentation(sourceSetData: DokkaSourceSet): String = - documentation[sourceSetData]?.children?.firstIsInstanceOrNull<T>()?.root?.children?.firstIsInstanceOrNull<Text>()?.body.orEmpty() + private inline fun <reified T: TagWrapper> Documentable.findNodeInDocumentation(sourceSetData: SourceSetData?): T? = + documentation[sourceSetData]?.firstChildOfType<T>() + + private fun Documentable.descriptionToContentNodes(sourceSet: SourceSetData? = mostTopSourceSet) = findNodeInDocumentation<Description>(sourceSet)?.let { + DocTagToContentConverter.buildContent( + it.root, + DCI(setOf(dri), JavadocContentKind.OverviewSummary), + sourceSets.toSet() + ) + }.orEmpty() + + private fun Documentable.brief(sourceSet: SourceSetData? = mostTopSourceSet): List<ContentNode> { + val description = descriptionToContentNodes(sourceSet) + val contents = mutableListOf<ContentNode>() + for (node in description) { + if ( node is ContentText && firstSentenceRegex.containsMatchIn(node.text) ) { + contents.add(node.copy(text = firstSentenceRegex.find(node.text)?.value.orEmpty())) + break + } else { + contents.add(node) + } + } + return contents + } } diff --git a/plugins/javadoc/src/main/kotlin/javadoc/KorteJavadocRenderer.kt b/plugins/javadoc/src/main/kotlin/javadoc/KorteJavadocRenderer.kt index 23a7c9ed..cec5bbca 100644 --- a/plugins/javadoc/src/main/kotlin/javadoc/KorteJavadocRenderer.kt +++ b/plugins/javadoc/src/main/kotlin/javadoc/KorteJavadocRenderer.kt @@ -238,7 +238,7 @@ class KorteJavadocRenderer(val outputWriter: OutputWriter, val context: DokkaCon val (modifiers, signature) = node.modifiersAndSignature return mapOf( "signature" to htmlForContentNode(node.signature), - "brief" to htmlForContentNode(node.brief), + "brief" to htmlForContentNodes(node.brief), "parameters" to node.parameters.map { renderParameterNode(it) }, "inlineParameters" to node.parameters.joinToString { "${it.type} ${it.name}" }, "modifiers" to htmlForContentNode(modifiers), @@ -249,7 +249,7 @@ class KorteJavadocRenderer(val outputWriter: OutputWriter, val context: DokkaCon private fun renderParameterNode(node: JavadocParameterNode): TemplateMap = mapOf( - "description" to htmlForContentNode(node.description), + "description" to htmlForContentNodes(node.description), "name" to node.name, "type" to node.type ) @@ -259,6 +259,7 @@ class KorteJavadocRenderer(val outputWriter: OutputWriter, val context: DokkaCon "constructors" to node.constructors.map { renderContentNodes(it) }, "signature" to htmlForContentNode(node.signature), "methods" to renderClasslikeMethods(node.methods), + "classlikeDocumentation" to renderContentNodes(node.description), "entries" to node.entries.map { renderEntryNode(it) }, "properties" to node.properties.map { renderPropertyNode(it) }, "classlikes" to node.classlikes.map { renderNestedClasslikeNode(it) }, @@ -304,7 +305,7 @@ class KorteJavadocRenderer(val outputWriter: OutputWriter, val context: DokkaCon return mapOf( "modifiers" to (node.modifiers + "static" + node.kind).joinToString(separator = " "), "signature" to node.name, - "description" to node.description + "description" to renderContentNodes(node.description) ) } @@ -313,7 +314,7 @@ class KorteJavadocRenderer(val outputWriter: OutputWriter, val context: DokkaCon return mapOf( "modifiers" to htmlForContentNode(modifiers), "signature" to htmlForContentNode(signature), - "description" to htmlForContentNode(node.brief) + "description" to htmlForContentNodes(node.brief) ) } @@ -324,6 +325,8 @@ class KorteJavadocRenderer(val outputWriter: OutputWriter, val context: DokkaCon ) } + private fun renderContentNodes(nodes: List<ContentNode>): String = nodes.joinToString(separator = "") { htmlForContentNode(it) } + fun htmlForContentNode(node: ContentNode): String = when (node) { is ContentGroup -> node.children.joinToString(separator = "") { htmlForContentNode(it) } @@ -333,9 +336,18 @@ class KorteJavadocRenderer(val outputWriter: OutputWriter, val context: DokkaCon node.address, node.sourceSets )}">${node.children.joinToString { htmlForContentNode(it) }} </a>""".trimMargin() + is ContentCode -> renderCode(node.children) else -> "" } + private fun renderCode(code: List<ContentNode>) : String = code.map { element -> + when (element) { + is ContentText -> element.text + is ContentBreakLine -> "" + else -> run { context.logger.error("Cannot cast $element as ContentText!"); "" } + } + }.joinToString("<br>", "<span class=\"code\">", "</span>") { it } + fun renderJavadocContentNode(node: JavadocContentNode): TemplateMap = when (node) { is TitleNode -> renderTitleNode(node) is JavadocContentGroup -> renderJavadocContentGroup(node) @@ -347,6 +359,7 @@ class KorteJavadocRenderer(val outputWriter: OutputWriter, val context: DokkaCon private fun renderTitleNode(node: TitleNode): TemplateMap { return mapOf( "title" to node.title, + "subtitle" to htmlForContentNodes(node.subtitle), "version" to node.version, "packageName" to node.parent ) diff --git a/plugins/javadoc/src/main/kotlin/javadoc/pages/JavadocContentNodes.kt b/plugins/javadoc/src/main/kotlin/javadoc/pages/JavadocContentNodes.kt index 286223fa..5b45bdf7 100644 --- a/plugins/javadoc/src/main/kotlin/javadoc/pages/JavadocContentNodes.kt +++ b/plugins/javadoc/src/main/kotlin/javadoc/pages/JavadocContentNodes.kt @@ -65,23 +65,25 @@ class JavaContentGroupBuilder(val sourceSets: Set<DokkaSourceSet>) { class TitleNode( val title: String, + val subtitle: List<ContentNode>, val version: String, val parent: String?, val dri: Set<DRI>, val kind: Kind, sourceSets: Set<DokkaSourceSet> ) : JavadocContentNode(dri, kind, sourceSets) { - override fun hasAnyContent(): Boolean = !title.isBlank() || !version.isBlank() + override fun hasAnyContent(): Boolean = !title.isBlank() || !version.isBlank() || subtitle.isNotEmpty() } fun JavaContentGroupBuilder.title( title: String, + subtitle: List<ContentNode>, version: String, parent: String? = null, dri: Set<DRI>, kind: Kind ) { - list.add(TitleNode(title, version, parent, dri, kind, sourceSets)) + list.add(TitleNode(title, subtitle, version, parent, dri, kind, sourceSets)) } data class TextNode( diff --git a/plugins/javadoc/src/main/kotlin/javadoc/pages/JavadocPageNodes.kt b/plugins/javadoc/src/main/kotlin/javadoc/pages/JavadocPageNodes.kt index f583144f..5ac232d4 100644 --- a/plugins/javadoc/src/main/kotlin/javadoc/pages/JavadocPageNodes.kt +++ b/plugins/javadoc/src/main/kotlin/javadoc/pages/JavadocPageNodes.kt @@ -83,18 +83,18 @@ class JavadocPackagePageNode( data class JavadocEntryNode( val signature: ContentNode, - val brief: String + val brief: List<ContentNode> ) data class JavadocParameterNode( val name: String, val type: String, - val description: ContentNode + val description: List<ContentNode> ) data class JavadocPropertyNode( val signature: ContentNode, - val brief: ContentNode + val brief: List<ContentNode> ) { val modifiersAndSignature: Pair<ContentNode, ContentNode> get() = (signature as ContentGroup).splitSignatureIntoModifiersAndName() @@ -102,7 +102,7 @@ data class JavadocPropertyNode( data class JavadocFunctionNode( val signature: ContentNode, - val brief: ContentNode, + val brief: List<ContentNode>, val parameters: List<JavadocParameterNode>, override val name: String, override val dri: Set<DRI> = emptySet(), @@ -138,7 +138,7 @@ class JavadocClasslikePageNode( override val dri: Set<DRI>, val modifiers: List<String>, val signature: ContentNode, - val description: String, + val description: List<ContentNode>, val constructors: List<JavadocFunctionNode>, val methods: List<JavadocFunctionNode>, val entries: List<JavadocEntryNode>, diff --git a/plugins/javadoc/src/main/resources/views/components/indexPage.korte b/plugins/javadoc/src/main/resources/views/components/indexPage.korte index 49d0fea2..adba2457 100644 --- a/plugins/javadoc/src/main/resources/views/components/indexPage.korte +++ b/plugins/javadoc/src/main/resources/views/components/indexPage.korte @@ -2,6 +2,12 @@ <div class="header"> <h1 {{ h1Title(kind)|raw }}class="title">{{ title }} {{ version }} API</h1> </div> + <div class="header"> + <div class="subtitle"> + <div class="block">{{ subtitle }}</div> + </div> + <p>See: <a href="#overview_description">Description</a></p> + </div> <div class="contentContainer"> <div class="overviewSummary"> {% include "components/indexTable.korte" %} |