diff options
Diffstat (limited to 'plugins/base/src')
4 files changed, 349 insertions, 356 deletions
diff --git a/plugins/base/src/main/kotlin/translators/documentables/DefaultDocumentableToPageTranslator.kt b/plugins/base/src/main/kotlin/translators/documentables/DefaultDocumentableToPageTranslator.kt index f577c8f4..2d9bab90 100644 --- a/plugins/base/src/main/kotlin/translators/documentables/DefaultDocumentableToPageTranslator.kt +++ b/plugins/base/src/main/kotlin/translators/documentables/DefaultDocumentableToPageTranslator.kt @@ -6,20 +6,10 @@ import org.jetbrains.dokka.pages.ModulePageNode import org.jetbrains.dokka.transformers.documentation.DocumentableToPageTranslator import org.jetbrains.dokka.utilities.DokkaLogger - class DefaultDocumentableToPageTranslator( private val commentsToContentConverter: CommentsToContentConverter, private val logger: DokkaLogger ) : DocumentableToPageTranslator { override fun invoke(module: Module): ModulePageNode = - DefaultPageBuilder { node, kind, operation -> - DefaultPageContentBuilder.group( - setOf(node.dri), - node.platformData, - kind, - commentsToContentConverter, - logger, - operation - ) - }.pageForModule(module) + DefaultPageCreator(commentsToContentConverter, logger).pageForModule(module) }
\ No newline at end of file diff --git a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt new file mode 100644 index 00000000..d6880f01 --- /dev/null +++ b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt @@ -0,0 +1,126 @@ +package org.jetbrains.dokka.base.translators.documentables + +import org.jetbrains.dokka.base.transformers.pages.comments.CommentsToContentConverter +import org.jetbrains.dokka.model.* +import org.jetbrains.dokka.model.Enum +import org.jetbrains.dokka.model.Function +import org.jetbrains.dokka.model.doc.TagWrapper +import org.jetbrains.dokka.pages.* +import org.jetbrains.dokka.utilities.DokkaLogger + +open class DefaultPageCreator( + commentsToContentConverter: CommentsToContentConverter, + val logger: DokkaLogger +) { + protected open val contentBuilder = PageContentBuilder(commentsToContentConverter, logger) + + open fun pageForModule(m: Module): ModulePageNode = + ModulePageNode(m.name.ifEmpty { "root" }, contentForModule(m), m, m.packages.map { pageForPackage(it) }) + + open fun pageForPackage(p: Package): PackagePageNode = + PackagePageNode(p.name, contentForPackage(p), setOf(p.dri), p, + p.classlikes.map { pageForClasslike(it) } + + p.functions.map { pageForMember(it) } + + p.packages.map { pageForPackage(it) }) + + open fun pageForClasslike(c: Classlike): ClasslikePageNode { + val constructors = when (c) { + is Class -> c.constructors + is Enum -> c.constructors + else -> emptyList() + } + + return ClasslikePageNode(c.name.orEmpty(), contentForClasslike(c), setOf(c.dri), c, + constructors.map { pageForMember(it) } + + c.classlikes.map { pageForClasslike(it) } + + c.functions.map { pageForMember(it) }) + } + + open fun pageForMember(c: Callable): MemberPageNode = when (c) { + is Function -> MemberPageNode(c.name, contentForFunction(c), setOf(c.dri), c) + else -> throw IllegalStateException("$c should not be present here") + } + + protected open fun contentForModule(m: Module) = contentBuilder.contentFor(m) { + header(1) { text("root") } + block("Packages", 2, ContentKind.Packages, m.packages, m.platformData.toSet()) { + link(it.name, it.dri) + } + text("Index\n") + text("Link to allpage here") + } + + protected open fun contentForPackage(p: Package) = contentBuilder.contentFor(p) { + header(1) { text("Package ${p.name}") } + block("Types", 2, ContentKind.Properties, p.classlikes, p.platformData.toSet()) { + link(it.name.orEmpty(), it.dri) + text(it.briefDocTagString) + } + block("Functions", 2, ContentKind.Functions, p.functions, p.platformData.toSet()) { + link(it.name, it.dri) + signature(it) + text(it.briefDocTagString) + } + } + + protected open fun contentForClasslike(c: Classlike) = contentBuilder.contentFor(c) { + when (c) { // TODO this when will be removed when signature generation is moved to utils + is Class -> header(1) { text(c.name) } + is Enum -> { + header(1) { text("enum ${c.name}") } + block("Entries", 2, ContentKind.Properties, c.entries, c.platformData.toSet()) { entry -> + link(entry.name.orEmpty(), entry.dri) + contentForComments(entry) + } + } + else -> throw IllegalStateException("$c should not be present here") + } + + contentForComments(c) + + if (c is WithConstructors) { + block("Constructors", 2, ContentKind.Functions, c.constructors, c.platformData.toSet()) { + link(it.name, it.dri) + signature(it) + text(it.briefDocTagString) + } + } + + block("Functions", 2, ContentKind.Functions, c.functions, c.platformData.toSet()) { + link(it.name, it.dri) + signature(it) + text(it.briefDocTagString) + } + + block("Properties", 2, ContentKind.Properties, c.properties, c.platformData.toSet()) { + link(it.name, it.dri) + text(it.briefDocTagString) + } + } + + protected open fun contentForComments(d: Documentable) = contentBuilder.contentFor(d) { + // TODO: this probably needs fixing + d.documentation.forEach { _, documentationNode -> + documentationNode.children.forEach { + header(3) { + text(it.toHeaderString()) + d.documentation.keys.joinToString(prefix = "[", postfix = "]", separator = ", ") + } + comment(it.root) + text("\n") + } + } + } + + protected open fun contentForFunction(f: Function) = contentBuilder.contentFor(f) { + header(1) { text(f.name) } + signature(f) + contentForComments(f) + block("Parameters", 2, ContentKind.Parameters, f.children, f.platformData.toSet()) { + text(it.name ?: "<receiver>") + it.documentation.forEach { it.value.children.forEach { comment(it.root) } } + } + } + + protected open fun TagWrapper.toHeaderString() = this.javaClass.toGenericString().split('.').last() +} diff --git a/plugins/base/src/main/kotlin/translators/documentables/PageBuilder.kt b/plugins/base/src/main/kotlin/translators/documentables/PageBuilder.kt deleted file mode 100644 index 82419a77..00000000 --- a/plugins/base/src/main/kotlin/translators/documentables/PageBuilder.kt +++ /dev/null @@ -1,159 +0,0 @@ -package org.jetbrains.dokka.base.translators.documentables - -import org.jetbrains.dokka.model.* -import org.jetbrains.dokka.model.Enum -import org.jetbrains.dokka.model.Function -import org.jetbrains.dokka.model.doc.TagWrapper -import org.jetbrains.dokka.pages.* - -open class DefaultPageBuilder( - override val rootContentGroup: RootContentBuilder -) : PageBuilder { - - override fun pageForModule(m: Module): ModulePageNode = - ModulePageNode(m.name.ifEmpty { "root" }, contentForModule(m), m, m.packages.map { pageForPackage(it) }) - - override fun pageForPackage(p: Package) = - PackagePageNode(p.name, contentForPackage(p), setOf(p.dri), p, - p.classlikes.map { pageForClasslike(it) } + - p.functions.map { pageForMember(it) }) - - override fun pageForClasslike(c: Classlike): ClasslikePageNode { - val constructors = when (c) { - is Class -> c.constructors - is Enum -> c.constructors - else -> emptyList() - } - - return ClasslikePageNode(c.name, contentForClasslike(c), setOf(c.dri), c, - constructors.map { pageForMember(it) } + - c.classlikes.map { pageForClasslike(it) } + - c.functions.map { pageForMember(it) }) - } - - override fun pageForMember(m: CallableNode): MemberPageNode = - when (m) { - is Function -> - MemberPageNode(m.name, contentForFunction(m), setOf(m.dri), m) - else -> throw IllegalStateException("$m should not be present here") - } - - protected open fun group(node: Documentable, content: PageContentBuilderFunction) = - rootContentGroup(node, ContentKind.Main, content) - - protected open fun contentForModule(m: Module) = group(m) { - header(1) { text("root") } - block("Packages", 2, ContentKind.Packages, m.packages, m.platformData) { - link(it.name, it.dri) - } - text("Index\n") - text("Link to allpage here") - } - - protected open fun contentForPackage(p: Package) = group(p) { - header(1) { text("Package ${p.name}") } - block("Types", 2, ContentKind.Properties, p.classlikes, p.platformData) { - link(it.name, it.dri) - text(it.briefDocTagString) - } - block("Functions", 2, ContentKind.Functions, p.functions, p.platformData) { - link(it.name, it.dri) - signature(it) - text(it.briefDocTagString) - } - } - - open fun contentForClasslike(c: Classlike): ContentGroup = when (c) { - is Class -> contentForClass(c) - is Enum -> contentForEnum(c) - else -> throw IllegalStateException("$c should not be present here") - } - - protected fun contentForClass(c: Class) = group(c) { - header(1) { text(c.name) } - - c.inherited.takeIf { it.isNotEmpty() }?.let { - header(2) { text("SuperInterfaces") } - linkTable(it) - } - contentForComments(c) - block("Constructors", 2, ContentKind.Functions, c.constructors, c.platformData) { - link(it.name, it.dri) - signature(it) - text(it.briefDocTagString) - } - block("Functions", 2, ContentKind.Functions, c.functions, c.platformData) { - link(it.name, it.dri) - signature(it) - text(it.briefDocTagString) - } - block("Properties", 2, ContentKind.Properties, c.properties, c.platformData) { - link(it.name, it.dri) - text(it.briefDocTagString) - - } - } - - fun contentForEnum(c: Enum): ContentGroup = group(c) { - header(1) { text("enum ${c.name}") } - - block("Entries", 2, ContentKind.Properties, c.entries, c.platformData) { entry -> - link(entry.name, entry.dri) - contentForComments(entry) - } - - c.inherited.takeIf { it.isNotEmpty() }?.let { - header(2) { text("SuperInterfaces") } - linkTable(it) - } - contentForComments(c) - block("Constructors", 2, ContentKind.Functions, c.constructors, c.platformData) { - link(it.name, it.dri) - signature(it) - text(it.briefDocTagString) - } - block("Functions", 2, ContentKind.Functions, c.functions, c.platformData) { - link(it.name, it.dri) - signature(it) - text(it.briefDocTagString) - } - block("Properties", 2, ContentKind.Properties, c.properties, c.platformData) { - link(it.name, it.dri) - text(it.briefDocTagString) - } - } - - private fun PageContentBuilder.contentForComments(d: Documentable) = - d.platformInfo.forEach { platformInfo -> - platformInfo.documentationNode.children.forEach { - header(3) { - text(it.toHeaderString()) - text(" [${platformInfo.platformData.joinToString(", ") { it.platformType.name }}]") - } - comment(it.root) - text("\n") - } - } - - private fun contentForFunction(f: Function) = group(f) { - header(1) { text(f.name) } - signature(f) - contentForComments(f) - block("Parameters", 2, ContentKind.Parameters, f.children, f.platformData) { - text(it.name ?: "<receiver>") - it.platformInfo.forEach { it.documentationNode.children.forEach { comment(it.root) } } - } - } - - private fun TagWrapper.toHeaderString() = this.javaClass.toGenericString().split('.').last() -} - -typealias RootContentBuilder = (Documentable, Kind, PageContentBuilderFunction) -> ContentGroup - -interface PageBuilder { - val rootContentGroup: RootContentBuilder - fun pageForModule(m: Module): ModulePageNode - fun pageForPackage(p: Package): PackagePageNode - fun pageForMember(m: CallableNode): MemberPageNode - fun pageForClasslike(c: Classlike): ClasslikePageNode -}
\ No newline at end of file diff --git a/plugins/base/src/main/kotlin/translators/documentables/PageContentBuilder.kt b/plugins/base/src/main/kotlin/translators/documentables/PageContentBuilder.kt index 48456910..588d9cb8 100644 --- a/plugins/base/src/main/kotlin/translators/documentables/PageContentBuilder.kt +++ b/plugins/base/src/main/kotlin/translators/documentables/PageContentBuilder.kt @@ -9,210 +9,246 @@ import org.jetbrains.dokka.model.doc.DocTag import org.jetbrains.dokka.pages.* import org.jetbrains.dokka.utilities.DokkaLogger -open class DefaultPageContentBuilder( - protected val dri: Set<DRI>, - protected val platformData: Set<PlatformData>, - protected val kind: Kind, - protected val commentsConverter: CommentsToContentConverter, - val logger: DokkaLogger, - protected val styles: Set<Style> = emptySet(), - protected val extras: Set<Extra> = emptySet() -) : PageContentBuilder { - protected val contents = mutableListOf<ContentNode>() - - protected fun createText(text: String, kind: Kind = ContentKind.Symbol) = - ContentText(text, DCI(dri, kind), platformData, styles, extras) - - protected fun build() = ContentGroup( - contents.toList(), - DCI(dri, kind), - platformData, - styles, - extras - ) - - override fun header(level: Int, block: PageContentBuilderFunction) { - contents += ContentHeader(level, group(ContentKind.Symbol, block)) - } - - override fun text(text: String, kind: Kind) { - contents += createText(text, kind) - } +@DslMarker +annotation class ContentBuilderMarker + +@ContentBuilderMarker +open class PageContentBuilder( + val commentsConverter: CommentsToContentConverter, + val logger: DokkaLogger +) { + fun contentFor( + dri: DRI, + platformData: Set<PlatformData>, + kind: Kind = ContentKind.Main, + styles: Set<Style> = emptySet(), + extras: Set<Extra> = emptySet(), + block: DocumentableContentBuilder.() -> Unit + ): ContentGroup = + DocumentableContentBuilder(dri, platformData, styles, extras) + .apply(block) + .build(platformData, kind, styles, extras) + + fun contentFor( + d: Documentable, + kind: Kind = ContentKind.Main, + styles: Set<Style> = emptySet(), + extras: Set<Extra> = emptySet(), + block: DocumentableContentBuilder.() -> Unit + ): ContentGroup = + DocumentableContentBuilder(d.dri, d.platformData.toSet(), styles, extras) + .apply(block) + .build(d.platformData.toSet(), kind, styles, extras) + + @ContentBuilderMarker + open inner class DocumentableContentBuilder( + val mainDRI: DRI, + val mainPlatformData: Set<PlatformData>, + val mainStyles: Set<Style>, + val mainExtras: Set<Extra> + ) { + protected val contents = mutableListOf<ContentNode>() - protected fun signature(f: Function, block: PageContentBuilderFunction) { - contents += group(setOf(f.dri), f.platformData, ContentKind.Symbol, block) - } + fun build( + platformData: Set<PlatformData>, + kind: Kind, + styles: Set<Style>, + extras: Set<Extra> + ) = ContentGroup( + contents.toList(), + DCI(setOf(mainDRI), kind), + platformData, + styles, + extras + ) - override fun signature(f: Function) = signature(f) { - text("fun ") - f.receiver?.also { - type(it.type) - text(".") - } - link(f.name, f.dri) - text("(") - list(f.parameters) { - link(it.name!!, it.dri) - text(": ") - type(it.type) - } - text(")") - val returnType = f.returnType - if (!f.isConstructor && returnType != null && - returnType.constructorFqName != Unit::class.qualifiedName + fun header( + level: Int, + kind: Kind = ContentKind.Main, + styles: Set<Style> = mainStyles, + extras: Set<Extra> = mainExtras, + block: DocumentableContentBuilder.() -> Unit ) { - text(": ") - type(returnType) + contents += ContentHeader( + level, + this@PageContentBuilder.contentFor(mainDRI, mainPlatformData, kind, styles, extras, block) + ) } - } - - override fun linkTable(elements: List<DRI>) { - contents += ContentTable( - emptyList(), - elements.map { group(dri, platformData, ContentKind.Classes) { link(it.classNames ?: "", it) } }, - DCI(dri, kind), - platformData, styles, extras - ) - } - override fun <T : Documentable> block( - name: String, - level: Int, - kind: Kind, - elements: Iterable<T>, - platformData: Set<PlatformData>, - operation: PageContentBuilder.(T) -> Unit - ) { - header(level) { text(name) } + fun text( + text: String, + kind: Kind = ContentKind.Main, + platformData: Set<PlatformData> = mainPlatformData, + styles: Set<Style> = mainStyles, + extras: Set<Extra> = mainExtras + ) { + contents += createText(text, kind, platformData, styles, extras) + } - contents += ContentTable( - emptyList(), - elements.map { group(setOf(it.dri), it.platformData, kind) { operation(it) } }, - DCI(dri, kind), - platformData, styles, extras - ) - } + fun signature(f: Function, block: DocumentableContentBuilder.() -> Unit) { + contents += group(f.dri, f.platformData.toSet(), ContentKind.Symbol, mainStyles, mainExtras, block) + } - override fun <T> list( - elements: List<T>, - prefix: String, - suffix: String, - separator: String, - operation: PageContentBuilder.(T) -> Unit - ) { - if (elements.isNotEmpty()) { - if (prefix.isNotEmpty()) text(prefix) - elements.dropLast(1).forEach { - operation(it) - text(separator) + fun signature(f: Function) = signature(f) { + text("fun ") + f.receiver?.also { + // TODO signature should be rewritten + type(it.type) + text(".") + } + link(f.name, f.dri) + text("(") + list(f.parameters) { + link(it.name!!, it.dri) + text(": ") + type(it.type) + } + text(")") + val returnType = f.type + if (!f.isConstructor && returnType.constructorFqName != Unit::class.qualifiedName) { + text(": ") + type(returnType) } - operation(elements.last()) - if (suffix.isNotEmpty()) text(suffix) } - } - override fun link(text: String, address: DRI, kind: Kind) { - contents += ContentDRILink( - listOf(createText(text)), - address, - DCI(dri, kind), - platformData - ) - } + fun linkTable( + elements: List<DRI>, + kind: Kind = ContentKind.Main, + platformData: Set<PlatformData> = mainPlatformData, + styles: Set<Style> = mainStyles, + extras: Set<Extra> = mainExtras + ) { + contents += ContentTable( + emptyList(), + elements.map { + this@PageContentBuilder.contentFor(it, platformData, kind, styles, extras) { + link(it.classNames ?: "", it) + } + }, + DCI(setOf(mainDRI), kind), + platformData, styles, extras + ) + } - override fun link(address: DRI, kind: Kind, block: PageContentBuilderFunction) { - contents += ContentDRILink( - group(ContentKind.Main, block).children, - address, - DCI(dri, kind), - platformData - ) - } + fun <T : Documentable> block( + name: String, + level: Int, + kind: Kind = ContentKind.Main, + elements: Iterable<T>, + platformData: Set<PlatformData> = mainPlatformData, + styles: Set<Style> = mainStyles, + extras: Set<Extra> = mainExtras, + operation: DocumentableContentBuilder.(T) -> Unit + ) { + header(level) { text(name) } + contents += ContentTable( + emptyList(), + elements.map { + group(it.dri, it.platformData.toSet(), kind, styles, extras) { + // TODO this will fail + operation(it) + } + }, + DCI(setOf(mainDRI), kind), + platformData, styles, extras + ) + } - override fun comment(docTag: DocTag) { - contents += group(ContentKind.Comment) { - with(this as DefaultPageContentBuilder) { - contents += commentsConverter.buildContent( - docTag, - DCI(dri, ContentKind.Comment), - platformData - ) + fun <T> list( + elements: List<T>, + prefix: String = "", + suffix: String = "", + separator: String = ",", + operation: DocumentableContentBuilder.(T) -> Unit + ) { + if (elements.isNotEmpty()) { + if (prefix.isNotEmpty()) text(prefix) + elements.dropLast(1).forEach { + operation(it) + text(separator) + } + operation(elements.last()) + if (suffix.isNotEmpty()) text(suffix) } } - } - fun group(kind: Kind, block: PageContentBuilderFunction): ContentGroup = - group(dri, platformData, kind, block) + fun link( + text: String, + address: DRI, + kind: Kind = ContentKind.Main, + platformData: Set<PlatformData> = mainPlatformData, + styles: Set<Style> = mainStyles, + extras: Set<Extra> = mainExtras + ) { + contents += ContentDRILink( + listOf(createText(text, kind, platformData, styles, extras)), + address, + DCI(setOf(mainDRI), kind), + platformData + ) + } - override fun group( - dri: Set<DRI>, - platformData: Set<PlatformData>, - kind: Kind, - block: PageContentBuilderFunction - ): ContentGroup = group(dri, platformData, kind, commentsConverter, logger, block) + fun link( + address: DRI, + kind: Kind = ContentKind.Main, + platformData: Set<PlatformData> = mainPlatformData, + styles: Set<Style> = mainStyles, + extras: Set<Extra> = mainExtras, + block: DocumentableContentBuilder.() -> Unit + ) { + contents += ContentDRILink( + this@PageContentBuilder.contentFor(mainDRI, platformData, kind, styles, extras, block).children, + address, + DCI(setOf(mainDRI), kind), + platformData + ) + } + + fun comment( + docTag: DocTag, + kind: Kind = ContentKind.Comment, + platformData: Set<PlatformData> = mainPlatformData, + styles: Set<Style> = mainStyles, + extras: Set<Extra> = mainExtras + ) { + val content = this@PageContentBuilder.commentsConverter.buildContent( + docTag, + DCI(setOf(mainDRI), kind), + platformData + ) + contents += ContentGroup(content, DCI(setOf(mainDRI), kind), platformData, styles, extras) + } - companion object { fun group( - dri: Set<DRI>, - platformData: Set<PlatformData>, + dri: DRI = mainDRI, + platformData: Set<PlatformData> = mainPlatformData, + kind: Kind = ContentKind.Main, + styles: Set<Style> = mainStyles, + extras: Set<Extra> = mainExtras, + block: DocumentableContentBuilder.() -> Unit + ): ContentGroup = this@PageContentBuilder.contentFor(dri, platformData, kind, styles, extras, block) + + protected fun createText( + text: String, kind: Kind, - commentsConverter: CommentsToContentConverter, - logger: DokkaLogger, - block: PageContentBuilderFunction - ): ContentGroup = - DefaultPageContentBuilder(dri, platformData, kind, commentsConverter, logger).apply(block).build() - } -} - - -fun PageContentBuilder.type(t: TypeWrapper) { - if (t.constructorNamePathSegments.isNotEmpty() && t.dri != null) - link(t.constructorNamePathSegments.last(), t.dri!!) - else if (t.constructorNamePathSegments.isNotEmpty() && t.dri == null) - text(t.toString()) - else (this as? DefaultPageContentBuilder)?.let { - logger.error("type $t cannot be resolved") - text("???") - } - list(t.arguments, prefix = "<", suffix = ">") { - type(it) + platformData: Set<PlatformData>, + styles: Set<Style>, + extras: Set<Extra> + ) = + ContentText(text, DCI(setOf(mainDRI), kind), platformData, styles, extras) + + fun type(t: TypeWrapper) { + if (t.constructorNamePathSegments.isNotEmpty() && t.dri != null) + link(t.constructorNamePathSegments.last(), t.dri!!) + else if (t.constructorNamePathSegments.isNotEmpty() && t.dri == null) + text(t.toString()) + else { + this@PageContentBuilder.logger.error("type $t cannot be resolved") + text("???") + } + list(t.arguments, prefix = "<", suffix = ">") { + type(it) + } + } } -} - -typealias PageContentBuilderFunction = PageContentBuilder.() -> Unit - -@DslMarker -annotation class ContentMarker - -@ContentMarker -interface PageContentBuilder { - fun group( - dri: Set<DRI>, - platformData: Set<PlatformData>, - kind: Kind, block: PageContentBuilderFunction - ): ContentGroup - - fun text(text: String, kind: Kind = ContentKind.Symbol) - fun signature(f: Function) - fun link(text: String, address: DRI, kind: Kind = ContentKind.Symbol) - fun link(address: DRI, kind: Kind = ContentKind.Symbol, block: PageContentBuilderFunction) - fun linkTable(elements: List<DRI>) - fun comment(docTag: DocTag) - fun header(level: Int, block: PageContentBuilderFunction) - fun <T> list( - elements: List<T>, - prefix: String = "", - suffix: String = "", - separator: String = ",", - operation: PageContentBuilder.(T) -> Unit - ) - - fun <T : Documentable> block( - name: String, - level: Int, - kind: Kind, - elements: Iterable<T>, - platformData: Set<PlatformData>, - operation: PageContentBuilder.(T) -> Unit - ) }
\ No newline at end of file |