diff --git a/libraries/kdoc/pom.xml b/libraries/kdoc/pom.xml index 86f21488e1d..772fd08c13b 100644 --- a/libraries/kdoc/pom.xml +++ b/libraries/kdoc/pom.xml @@ -6,9 +6,9 @@ 4.0.0 - org.jetbrains.kotlin - kotlin-project - 1.0-SNAPSHOT + org.jetbrains.kotlin + kotlin-project + 1.0-SNAPSHOT kdoc @@ -17,7 +17,7 @@ org.pegdown pegdown - 1.1.0 + ${pegdown.version} diff --git a/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/model/KotlinModel.kt b/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/model/KotlinModel.kt index 15663746256..2e6a5ba30a1 100644 --- a/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/model/KotlinModel.kt +++ b/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/model/KotlinModel.kt @@ -30,6 +30,7 @@ import org.pegdown.ast.RefLinkNode import org.pegdown.ast.AutoLinkNode import org.pegdown.ast.ExpLinkNode import org.pegdown.Extensions +import org.jetbrains.kotlin.doc.templates.KDocTemplate fun containerName(descriptor: DeclarationDescriptor): String = qualifiedName(descriptor.getContainingDeclaration()) @@ -119,7 +120,7 @@ fun extensionProperties(properties: Collection): Map = TreeSet() @@ -183,7 +184,7 @@ class KModel(var context: BindingContext, val config: KDocConfig, var title: Str KPackage(this, descriptor, name) } if (created) { - pkg.description = commentsFor(descriptor) + configureComments(pkg, descriptor) val scope = descriptor.getMemberScope() addFunctions(pkg, scope) pkg.local = isLocal(descriptor) @@ -191,6 +192,10 @@ class KModel(var context: BindingContext, val config: KDocConfig, var title: Str return pkg; } + fun wikiConvert(text: String, linkRenderer: LinkRenderer): String { + return markdownProcessor.markdownToHtml(text, linkRenderer).sure() + } + protected fun isLocal(descriptor: DeclarationDescriptor): Boolean { return if (descriptor is ModuleDescriptor) { true @@ -249,7 +254,7 @@ class KModel(var context: BindingContext, val config: KDocConfig, var title: Str } val function = KFunction(descriptor, owner, name, returnType, parameters) addTypeParameters(function.typeParameters, descriptor.getTypeParameters()) - function.description = commentsFor(descriptor) + configureComments(function, descriptor) val receiver = descriptor.getReceiverParameter() if (receiver is ExtensionReceiver) { function.extensionClass = getType(receiver.getType())?.klass @@ -272,8 +277,8 @@ class KModel(var context: BindingContext, val config: KDocConfig, var title: Str protected fun createTypeParameter(descriptor: TypeParameterDescriptor): KTypeParameter? { val name = descriptor.getName() - val answer = KTypeParameter(name, descriptor) - answer.description = commentsFor(descriptor) + val answer = KTypeParameter(name, descriptor, this) + configureComments(answer, descriptor) return answer } @@ -282,14 +287,15 @@ class KModel(var context: BindingContext, val config: KDocConfig, var title: Str if (returnType != null) { val name = descriptor.getName() val answer = KParameter(name, returnType) - answer.description = commentsFor(descriptor) + configureComments(answer, descriptor) return answer } return null } - fun commentsFor(descriptor: DeclarationDescriptor): String { + + protected fun commentsFor(descriptor: DeclarationDescriptor): String { val psiElement = try { BindingContextUtils.descriptorToDeclaration(context, descriptor) } catch (e: Throwable) { @@ -328,8 +334,7 @@ class KModel(var context: BindingContext, val config: KDocConfig, var title: Str } buffer.append(text) } - val linkRenderer = CustomLinkRenderer(descriptor) - return wikiConvert(buffer.toString() ?: "", linkRenderer) + return buffer.toString() ?: "" } else { return text } @@ -337,8 +342,9 @@ class KModel(var context: BindingContext, val config: KDocConfig, var title: Str return "" } - fun wikiConvert(text: String, linkRenderer: LinkRenderer): String { - return markdownProcessor.markdownToHtml(text, linkRenderer).sure() + fun configureComments(annotated: KAnnotated, descriptor: DeclarationDescriptor): Unit { + val detailedText = commentsFor(descriptor).trim() + annotated.wikiDescription = detailedText } fun getType(aType: JetType?): KType? { @@ -375,7 +381,7 @@ class KModel(var context: BindingContext, val config: KDocConfig, var title: Str } } -class CustomLinkRenderer(descriptor: DeclarationDescriptor) : LinkRenderer() { +class TemplateLinkRenderer(template: KDocTemplate) : LinkRenderer() { override fun render(node : WikiLinkNode?) : Rendering? { println("LinkRenderer.render(WikiLinkNode): $node") @@ -399,16 +405,27 @@ class CustomLinkRenderer(descriptor: DeclarationDescriptor) : LinkRenderer() { } } -abstract class KAnnotated { - public open var description: String = "" - - public open var detailedDescription: String = "" - get() = if ($detailedDescription.notEmpty()) $detailedDescription else description +abstract class KAnnotated(val model: KModel) { + public open var wikiDescription: String = "" public open var deprecated: Boolean = false + + fun description(template: KDocTemplate): String { + val detailedText = detailedDescription(template) + val idx = detailedText.indexOf("

") + return if (idx > 0) { + detailedText.substring(0, idx).trimLeading("

") + } else { + detailedText + } + } + + fun detailedDescription(template: KDocTemplate): String { + return model.wikiConvert(wikiDescription, TemplateLinkRenderer(template)) + } } -abstract class KNamed(val name: String) : KAnnotated(), Comparable { +abstract class KNamed(val name: String, model: KModel) : KAnnotated(model), Comparable { override fun compareTo(other: KNamed): Int = name.compareTo(other.name) @@ -418,9 +435,9 @@ abstract class KNamed(val name: String) : KAnnotated(), Comparable { } -class KPackage(val model: KModel, val descriptor: NamespaceDescriptor, +class KPackage(model: KModel, val descriptor: NamespaceDescriptor, val name: String, - var local: Boolean = false) : KClassOrPackage(), Comparable { + var local: Boolean = false) : KClassOrPackage(model), Comparable { override fun compareTo(other: KPackage): Int = name.compareTo(other.name) @@ -435,7 +452,7 @@ class KPackage(val model: KModel, val descriptor: NamespaceDescriptor, KClass(this, descriptor, name) } if (created) { - klass.description = model.commentsFor(descriptor) + model.configureComments(klass, descriptor) val typeConstructor = descriptor.getTypeConstructor() val superTypes = typeConstructor.getSupertypes() for (st in superTypes) { @@ -508,11 +525,10 @@ class KPackage(val model: KModel, val descriptor: NamespaceDescriptor, fun packageFunctions() = functions.filter{ it.extensionClass == null } } -class KType(val jetType: JetType, val model: KModel, val klass: KClass?, val arguments: List = ArrayList()) : KNamed(klass?.name ?: jetType.toString()) { +class KType(val jetType: JetType, model: KModel, val klass: KClass?, val arguments: List = ArrayList()) : KNamed(klass?.name ?: jetType.toString(), model) { { if (klass != null) { - this.description = klass.description - this.detailedDescription = klass.detailedDescription + this.wikiDescription = klass.wikiDescription } for (arg in jetType.getArguments()) { if (arg != null) { @@ -528,7 +544,7 @@ class KType(val jetType: JetType, val model: KModel, val klass: KClass?, val arg override fun toString() = if (nullable) "$name?" else name val nullable: Boolean - get() = jetType.isNullable() + get() = jetType.isNullable() } class KClass(val pkg: KPackage, val descriptor: ClassDescriptor, @@ -540,7 +556,7 @@ class KClass(val pkg: KPackage, val descriptor: ClassDescriptor, var authors: List = arrayList(), var baseClasses: List = arrayList(), var nestedClasses: List = arrayList(), - var sourceLine: Int = 2) : KClassOrPackage(), Comparable { + var sourceLine: Int = 2) : KClassOrPackage(pkg.model), Comparable { override fun compareTo(other: KClass): Int = name.compareTo(other.name) @@ -557,8 +573,6 @@ class KClass(val pkg: KPackage, val descriptor: ClassDescriptor, public val name: String = pkg.qualifiedName(simpleName) - public val model: KModel = pkg.model - public val packageName: String = pkg.name /** Returns the name as a directory using '/' instead of '.' */ @@ -590,7 +604,7 @@ class KFunction(val descriptor: CallableDescriptor, val owner: KClassOrPackage, var typeParameters: List = arrayList(), var exceptions: List = arrayList(), var annotations: List = arrayList(), - var sourceLine: Int = 2) : KAnnotated(), Comparable { + var sourceLine: Int = 2) : KAnnotated(owner.model), Comparable { public val parameterTypeText: String = parameters.map{ it.aType.name }.join(", ") @@ -608,7 +622,7 @@ class KFunction(val descriptor: CallableDescriptor, val owner: KClassOrPackage, } fun equals(other: KFunction) = name == other.name && this.parameterTypeText == other.parameterTypeText && - this.extensionClass == other.extensionClass && this.owner == other.owner + this.extensionClass == other.extensionClass && this.owner == other.owner fun toString() = "fun $name($parameterTypeText): $returnType" @@ -620,7 +634,7 @@ class KFunction(val descriptor: CallableDescriptor, val owner: KClassOrPackage, } class KProperty(val owner: KClassOrPackage, val descriptor: PropertyDescriptor, val name: String, - val returnType: KType, val extensionClass: KClass?) : KAnnotated(), Comparable { + val returnType: KType, val extensionClass: KClass?) : KAnnotated(owner.model), Comparable { override fun compareTo(other: KProperty): Int = name.compareTo(other.name) @@ -632,19 +646,20 @@ class KProperty(val owner: KClassOrPackage, val descriptor: PropertyDescriptor, } class KParameter(val name: String, - var aType: KType) : KAnnotated() { + var aType: KType) : KAnnotated(aType.model) { fun toString() = "$name: ${aType.name}" } class KTypeParameter(val name: String, val descriptor: TypeParameterDescriptor, - var extends: List = arrayList()) : KAnnotated() { + model: KModel, + var extends: List = arrayList()) : KAnnotated(model) { fun toString() = "$name" } -class KAnnotation(var klass: KClass) : KAnnotated() { +class KAnnotation(var klass: KClass) : KAnnotated(klass.model) { // TODO add some parameter values? diff --git a/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/ClassTemplate.kt b/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/ClassTemplate.kt index 70c3e672880..0d232e16ecb 100644 --- a/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/ClassTemplate.kt +++ b/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/ClassTemplate.kt @@ -195,7 +195,7 @@ Class ${klass.simpleName}

""") - println(klass.detailedDescription) + println(klass.detailedDescription(this)) if (klass.since.size > 0 || klass.authors.size > 0) { println("""

""") @@ -229,7 +229,7 @@ Class ${klass.simpleName} static class ${klass.simpleName}.${nc.simpleName}
-          ${nc.description} +          ${nc.description(this)} """) } println(""" diff --git a/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/OverviewSummaryTemplate.kt b/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/OverviewSummaryTemplate.kt index c9a737b8ce7..945f21900a7 100644 --- a/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/OverviewSummaryTemplate.kt +++ b/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/OverviewSummaryTemplate.kt @@ -105,7 +105,7 @@ ${model.title} for (p in model.packages) { println(""" ${p.name} -${p.description} +${p.description(this)} """) } println(""" diff --git a/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/PackageSummaryTemplate.kt b/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/PackageSummaryTemplate.kt index 7ba979f7e58..c961616cf6c 100644 --- a/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/PackageSummaryTemplate.kt +++ b/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/PackageSummaryTemplate.kt @@ -105,7 +105,7 @@ function windowTitle() println("""

Package ${pkg.name}

-${pkg.description} +${pkg.description(this)}

See:
@@ -127,7 +127,7 @@ Package ${pkg.name} Description

-${pkg.detailedDescription} +${pkg.detailedDescription(this)}

Contents

@@ -229,7 +229,7 @@ Copyright © 2010-2012. All Rights Reserved. for (c in classes) { println(""" ${c.simpleName} -${c.description} +${c.description(this)} """) } println(""" @@ -252,7 +252,7 @@ Copyright © 2010-2012. All Rights Reserved. for (f in functions) { println(""" ${f.name} -${f.description} +${f.description(this)} """) } println(""" diff --git a/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/PackageTemplateSupport.kt b/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/PackageTemplateSupport.kt index 22ec9d63861..72f817c0559 100644 --- a/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/PackageTemplateSupport.kt +++ b/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/PackageTemplateSupport.kt @@ -65,11 +65,11 @@ abstract class PackageTemplateSupport(open val pkg: KPackage) : KDocTemplate() { println("""""") println("") if (true) { - val detail = function.detailedDescription - println("""${detail}""") + println("""
""") + println("""${function.description(this)}""") } else { println("""
""") - println("""          ${deprecated} ${function.detailedDescription}""") + println("""          ${deprecated} ${function.detailedDescription(this)}""") } println("""""") println("""""") @@ -120,7 +120,7 @@ abstract class PackageTemplateSupport(open val pkg: KPackage) : KDocTemplate() { } println("""""") - println(function.detailedDescription) + println(function.detailedDescription(this)) /* TODO println("""
Deprecated. TODO text @@ -188,7 +188,7 @@ abstract class PackageTemplateSupport(open val pkg: KPackage) : KDocTemplate() { println("""""") println("""""") println("""
""") - println("""          ${deprecated} ${property.detailedDescription}""") + println("""          ${deprecated} ${property.detailedDescription(this)}""") println("""""") }