From 585625bf2fcc2c77fa7489c11fa0acb28f88b966 Mon Sep 17 00:00:00 2001 From: James Strachan Date: Wed, 7 Mar 2012 10:22:52 +0000 Subject: [PATCH] refactored the comments to split the wiki markup into the first paragraph for the summary and the rest for the detail and to allow relative URL links to classes in wiki links --- libraries/kdoc/pom.xml | 8 +- .../jetbrains/kotlin/doc/model/KotlinModel.kt | 83 +++++++++++-------- .../kotlin/doc/templates/ClassTemplate.kt | 4 +- .../doc/templates/OverviewSummaryTemplate.kt | 2 +- .../doc/templates/PackageSummaryTemplate.kt | 8 +- .../doc/templates/PackageTemplateSupport.kt | 10 +-- 6 files changed, 65 insertions(+), 50 deletions(-) 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("""""") }