From 68d8e7fba0975126c866dfed633c728e54dca8ee Mon Sep 17 00:00:00 2001 From: James Strachan Date: Fri, 30 Mar 2012 12:35:26 +0100 Subject: [PATCH] improved the kdoc format so it looks a bit more like kotlin code --- .../org/jetbrains/kotlin/doc/KDocConfig.kt | 2 +- .../jetbrains/kotlin/doc/model/KotlinModel.kt | 22 +++++--- .../kotlin/doc/templates/ClassTemplate.kt | 8 +-- .../doc/templates/PackageTemplateSupport.kt | 50 ++++++++++++++----- 4 files changed, 57 insertions(+), 25 deletions(-) diff --git a/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/KDocConfig.kt b/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/KDocConfig.kt index 50065d41567..7debc8f6007 100644 --- a/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/KDocConfig.kt +++ b/libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/KDocConfig.kt @@ -98,7 +98,7 @@ class KDocConfig() { } } -protected class LongestFirstStringComparator() : Comparator { +private class LongestFirstStringComparator() : Comparator { override fun compare(s1: String?, s2: String?): Int { return compareBy(s1, s2, { (s: String) -> s.length() }, { (s: String) -> s }) } 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 e5a005455e9..bd6b8f65858 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 @@ -38,6 +38,7 @@ import org.jetbrains.jet.lang.descriptors.ClassKind import com.intellij.psi.PsiElement import com.intellij.psi.PsiFile import com.intellij.psi.PsiDirectory +import org.jetbrains.jet.lang.descriptors.Visibilities /** @@ -254,7 +255,7 @@ class KModel(var context: BindingContext, val config: KDocConfig) { } } - protected fun addFunctions(owner: KClassOrPackage, scope: JetScope): Unit { + fun addFunctions(owner: KClassOrPackage, scope: JetScope): Unit { try { val descriptors = scope.getAllDescriptors() for (descriptor in descriptors) { @@ -303,14 +304,16 @@ class KModel(var context: BindingContext, val config: KDocConfig) { configureComments(function, descriptor) val receiver = descriptor.getReceiverParameter() if (receiver is ExtensionReceiver) { - function.extensionClass = getType(receiver.getType())?.klass + val receiverType = getType(receiver.getType()) + function.receiverType = receiverType + function.extensionClass = receiverType?.klass } return function } return null } - protected fun addTypeParameters(answer: List, descriptors: List): Unit { + fun addTypeParameters(answer: List, descriptors: List): Unit { for (typeParam in descriptors) { if (typeParam != null) { val p = createTypeParameter(typeParam) @@ -340,7 +343,7 @@ class KModel(var context: BindingContext, val config: KDocConfig) { } - protected fun fileFor(descriptor: DeclarationDescriptor): String? { + fun fileFor(descriptor: DeclarationDescriptor): String? { val psiElement = getPsiElement(descriptor) return psiElement?.getContainingFile()?.getName() } @@ -844,7 +847,7 @@ class KClass(val pkg: KPackage, val descriptor: ClassDescriptor, fun isApi(): Boolean { val visibility = descriptor.getVisibility() - return visibility.isAPI() + return visibility.isPublicAPI() } val kind: String @@ -870,9 +873,9 @@ class KClass(val pkg: KPackage, val descriptor: ClassDescriptor, val visibility: String get() { val v = descriptor.getVisibility() - return if (v == Visibility.PUBLIC) "public" - else if (v == Visibility.PROTECTED) "protected" - else if (v == Visibility.PRIVATE) "private" + return if (v == Visibilities.PUBLIC) "public" + else if (v == Visibilities.PROTECTED) "protected" + else if (v == Visibilities.PRIVATE) "private" else "" } @@ -911,6 +914,7 @@ class KClass(val pkg: KPackage, val descriptor: ClassDescriptor, class KFunction(val descriptor: CallableDescriptor, val owner: KClassOrPackage, val name: String, var returnType: KType, var parameters: List, + var receiverType: KType? = null, var extensionClass: KClass? = null, var modifiers: List = arrayList(), var typeParameters: List = arrayList(), @@ -954,6 +958,8 @@ class KProperty(val owner: KClassOrPackage, val descriptor: PropertyDescriptor, fun equals(other: KFunction) = name == other.name + fun isVar(): Boolean = descriptor.isVar() + fun toString() = "property $name" } 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 7227c04fdc0..fa990cc07b0 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 @@ -95,9 +95,9 @@ function windowTitle() - SUMMARY: NESTED | FIELD | CONSTR | METHOD + SUMMARY: NESTED | PROPERTY | CONSTR | FUNCTION -DETAIL: FIELD | CONSTR | METHOD +DETAIL: PROPERTY | CONSTR | FUNCTION @@ -151,9 +151,9 @@ DETAIL: FIELD | CONSTR | METHO - SUMMARY: NESTED | FIELD | CONSTR | METHOD + SUMMARY: NESTED | PROPERTY | CONSTR | FUNCTION - DETAIL: FIELD | CONSTR | METHOD + DETAIL: PROPERTY | CONSTR | FUNCTION 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 7b7d61282f4..087ca6b475e 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 @@ -18,6 +18,11 @@ abstract class PackageTemplateSupport(open val pkg: KPackage) : KDocTemplate() { protected override fun relativePrefix(): String = pkg.nameAsRelativePath + val funKeyword = keyword("fun") + val valKeyword = keyword("val") + val varKeyword = keyword("var") + + protected fun keyword(name: String): String = "$name" fun printFunctionSummary(functions: Collection): Unit { if (functions.notEmpty()) { @@ -40,6 +45,7 @@ abstract class PackageTemplateSupport(open val pkg: KPackage) : KDocTemplate() { } } + fun printFunctionSummary(function: KFunction): Unit { val deprecated = if (function.deprecated) "Deprecated." else "" print(""" @@ -50,18 +56,22 @@ abstract class PackageTemplateSupport(open val pkg: KPackage) : KDocTemplate() { """) + print("$funKeyword ") printTypeParameters(function) - println("""
""") - print(link(function.returnType)) + printReceiverType(function, "
") println(""" """) } else { - print(link(function.returnType)) + print(funKeyword) + printReceiverType(function) } + // print receiver type println("""""") print("""${function.name}""") printParameters(function) + print(": ") + print(link(function.returnType)) println("""""") println("") if (true) { @@ -75,6 +85,18 @@ abstract class PackageTemplateSupport(open val pkg: KPackage) : KDocTemplate() { println("""""") } + + fun printReceiverType(function: KFunction, prefix: String = " ", postfix: String = "", none: String = ""): Unit { + val receiverType = function.receiverType + if (receiverType != null) { + print(prefix) + print(link(receiverType)) + print(postfix) + } else { + print(none) + } + } + fun printFunctionDetail(functions: Collection): Unit { if (functions.notEmpty()) { println(""" @@ -102,13 +124,15 @@ abstract class PackageTemplateSupport(open val pkg: KPackage) : KDocTemplate() { println("""
""")
         println("""""")
         printAnnotations(function.annotations)
-        print("""${function.modifiers.join(" ")} """)
+        print("""${function.modifiers.join(" ")} $funKeyword""")
 
-        printTypeParameters(function)
+        printTypeParameters(function, " ")
+        printReceiverType(function, " ", ".", " ")
+        print("""${function.name}""")
+        printParameters(function)
+        print(": ")
         print(link(function.returnType))
 
-        print(""" ${function.name}""")
-        printParameters(function)
         val exlist = function.exceptions
         var first = true
         if (!exlist.isEmpty()) {
@@ -163,8 +187,9 @@ abstract class PackageTemplateSupport(open val pkg: KPackage) : KDocTemplate() {
     fun printPropertySummary(property: KProperty): Unit {
         val deprecated = if (property.deprecated) "Deprecated." else ""
         print("""
-
+
 """)
+        print(if (property.isVar()) varKeyword else valKeyword)
         /*
         if (!property.typeParameters.isEmpty()) {
             println("""
@@ -181,9 +206,9 @@ abstract class PackageTemplateSupport(open val pkg: KPackage) : KDocTemplate() {
             print(link(property.returnType))
         }
         */
-        print(link(property.returnType))
         println("""""")
-        print("""""")
     }
 
-    fun printTypeParameters(method: KFunction): Unit {
+    fun printTypeParameters(method: KFunction, separator: String = ""): Unit {
         val typeParameters = method.typeParameters
         if (!typeParameters.isEmpty()) {
+            print(separator)
             print("<")
             var separator = ""
             for (t in typeParameters) {
@@ -212,7 +238,7 @@ abstract class PackageTemplateSupport(open val pkg: KPackage) : KDocTemplate() {
                     }
                 }
             }
-            print("> ")
+            print(">")
         }
     }
 

${property.name}""")
+        print("""${property.name}: """)
+        print(link(property.returnType))
         //printParameters(property)
         println("""""")
         println("""""")
@@ -192,9 +217,10 @@ abstract class PackageTemplateSupport(open val pkg: KPackage) : KDocTemplate() {
         println("""