From beafb561bb1aca0ad891b47ed57a2fd62eee755f Mon Sep 17 00:00:00 2001 From: James Strachan Date: Fri, 9 Mar 2012 11:28:19 +0000 Subject: [PATCH] improved kdoc to avoid showing duplicate functions of the same name & to show more detail in the function summary table --- .../jetbrains/kotlin/doc/model/KotlinModel.kt | 68 +++++++++++-------- .../doc/templates/PackageFrameTemplate.kt | 13 +++- .../doc/templates/PackageSummaryTemplate.kt | 8 ++- 3 files changed, 57 insertions(+), 32 deletions(-) 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 a93cb515b30..3cebc244bd0 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 @@ -33,6 +33,21 @@ import org.pegdown.Extensions import org.jetbrains.kotlin.doc.templates.KDocTemplate import org.jetbrains.jet.lang.resolve.scopes.WritableScopeImpl + +/** + * Returns the collection of functions with duplicate function names filtered out + * so only the first one is included + */ +fun filterDuplicateNames(functions: Collection): Collection { + var lastName = "" + return functions.filter{ + val name = it.name + val answer = name != lastName + lastName = name + answer + } +} + fun containerName(descriptor: DeclarationDescriptor): String = qualifiedName(descriptor.getContainingDeclaration()) fun qualifiedName(descriptor: DeclarationDescriptor?): String { @@ -313,7 +328,6 @@ class KModel(var context: BindingContext, val config: KDocConfig) { } - protected fun commentsFor(descriptor: DeclarationDescriptor): String { val psiElement = try { BindingContextUtils.descriptorToDeclaration(context, descriptor) @@ -341,7 +355,7 @@ class KModel(var context: BindingContext, val config: KDocConfig) { var text = lines[i] ?: "" text = text.trim() if (i == 0) { - text = text.trimLeading("/**").trimLeading("/*") + text = text.trimLeading("/**").trimLeading("/*") } else { buffer.append("\n") } @@ -469,7 +483,7 @@ class TemplateLinkRenderer(val annotated: KAnnotated, val template: KDocTemplate val idx = qualifiedName.lastIndexOf('.') if (idx > 0) { val className = qualifiedName.substring(0, idx) - val c = model.getClass(className) + val c = model.getClass(className) if (c != null) { // lets try find method... val remaining = qualifiedName.substring(idx + 1) @@ -494,32 +508,32 @@ class TemplateLinkRenderer(val annotated: KAnnotated, val template: KDocTemplate protected fun resolveToQualifiedName(text: String): String { // TODO use the CompletionContributors maybe to figure out what local names are imported??? return text -/* - val scope = findWritableScope(annotated.declarationDescriptor) - if (scope != null) { - val classifierDescriptor = scope.getClassifier(text) - if (classifierDescriptor == null) { - val o = scope.getObjectDescriptor(text) - println("Attempt to resolve HREF: $text Found objectDescriptor $o") - } else { - println("Attempt to resolve HREF: $text Found classifierDescriptor $classifierDescriptor") + /* + val scope = findWritableScope(annotated.declarationDescriptor) + if (scope != null) { + val classifierDescriptor = scope.getClassifier(text) + if (classifierDescriptor == null) { + val o = scope.getObjectDescriptor(text) + println("Attempt to resolve HREF: $text Found objectDescriptor $o") + } else { + println("Attempt to resolve HREF: $text Found classifierDescriptor $classifierDescriptor") + } + } } - } - } - protected fun findWritableScope(declarationDescriptor: DeclarationDescriptor) : WritableScopeImpl? { - val container = declarationDescriptor.getContainingDeclaration() - if (container is NamespaceDescriptor) { - val scope = container.getMemberScope() - if (scope is WritableScopeImpl) { - return scope - } - } else if (container != null) { - return findWritableScope(container) - } - return null + protected fun findWritableScope(declarationDescriptor: DeclarationDescriptor) : WritableScopeImpl? { + val container = declarationDescriptor.getContainingDeclaration() + if (container is NamespaceDescriptor) { + val scope = container.getMemberScope() + if (scope is WritableScopeImpl) { + return scope + } + } else if (container != null) { + return findWritableScope(container) + } + return null -*/ + */ } override fun render(node : RefLinkNode?, url : String?, title : String?, text : String?) : Rendering? { @@ -661,7 +675,7 @@ class KPackage(model: KModel, val descriptor: NamespaceDescriptor, } class KType(val jetType: JetType, model: KModel, val klass: KClass?, val arguments: List = ArrayList()) - : KNamed(klass?.name ?: jetType.toString(), model, jetType.getConstructor().getDeclarationDescriptor().sure()) { +: KNamed(klass?.name ?: jetType.toString(), model, jetType.getConstructor().getDeclarationDescriptor().sure()) { { if (klass != null) { this.wikiDescription = klass.wikiDescription diff --git a/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/PackageFrameTemplate.kt b/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/PackageFrameTemplate.kt index 1651bd73a9e..a0d2e5a2b01 100644 --- a/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/PackageFrameTemplate.kt +++ b/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/PackageFrameTemplate.kt @@ -10,6 +10,7 @@ import org.jetbrains.kotlin.doc.model.KPackage import org.jetbrains.kotlin.doc.model.KClass import org.jetbrains.kotlin.doc.model.KFunction import org.jetbrains.kotlin.doc.model.extensionFunctions +import org.jetbrains.kotlin.doc.model.filterDuplicateNames class PackageFrameTemplate(val model: KModel, p: KPackage) : PackageTemplateSupport(p) { override fun render() { @@ -65,16 +66,22 @@ ${pkg.name} (${model.title}) } protected fun printFunctions(): Unit { - val functions = pkg.packageFunctions() + val functions = filterDuplicateNames(pkg.packageFunctions()) if (! functions.isEmpty()) { println("""
Functions 
""") + + var lastName = "" for (c in functions) { - println("""${c.name} -
""") + // only show the first function with a given name + if (c.name != lastName) { + println("""${c.name} +
""") + } + lastName = c.name } 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 c961616cf6c..88f5e0d526c 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 @@ -10,6 +10,7 @@ import org.jetbrains.kotlin.doc.model.KPackage import org.jetbrains.kotlin.doc.model.KClass import org.jetbrains.kotlin.doc.model.extensionFunctions import org.jetbrains.kotlin.doc.model.inheritedExtensionFunctions +import org.jetbrains.kotlin.doc.model.filterDuplicateNames class PackageSummaryTemplate(val model: KModel, pkg: KPackage) : PackageTemplateSupport(pkg) { override fun render() { @@ -119,7 +120,8 @@ ${pkg.description(this)} printClasses("annotation", "Annotations") printClasses("exception", "Exceptions") - printFunctions() + printFunctionSummary(pkg.packageFunctions()) + //printFunctions() printExtensionFunctions() println("""

@@ -240,6 +242,7 @@ Copyright © 2010-2012. All Rights Reserved. } } + // TODO delete protected fun printFunctions(): Unit { val functions = pkg.functions.filter{ it.extensionClass == null } if (! functions.isEmpty()) { @@ -280,7 +283,8 @@ Copyright © 2010-2012. All Rights Reserved. """) val list = e?.getValue() if (list != null) { - for (f in list) { + val functions = filterDuplicateNames(list) + for (f in functions) { println("""${f.name} """) } }