From de3d5edb2acb78618ab58461abfc1f1405e7f145 Mon Sep 17 00:00:00 2001 From: James Strachan Date: Fri, 24 Feb 2012 07:25:07 +0000 Subject: [PATCH] added support for properties in kdoc --- .../kotlin/doc/templates/ClassTemplate.kt | 1 + .../kotlin/doc/templates/KDocTemplate.kt | 19 ++- .../doc/templates/PackageTemplateSupport.kt | 118 +++++++++++++----- .../org/jetbrains/kotlin/model/KotlinModel.kt | 29 +++-- 4 files changed, 119 insertions(+), 48 deletions(-) diff --git a/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/ClassTemplate.kt b/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/ClassTemplate.kt index ae433e0442c..0d795c80cce 100644 --- a/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/ClassTemplate.kt +++ b/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/ClassTemplate.kt @@ -241,6 +241,7 @@ DETAIL: FIELD | CONSTR | METHO  """) } + printPropertySummary(klass.properties) printFunctionSummary(klass.functions) printFunctionDetail(klass.functions) diff --git a/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/KDocTemplate.kt b/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/KDocTemplate.kt index 79865287533..7ccd1dcc157 100644 --- a/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/KDocTemplate.kt +++ b/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/KDocTemplate.kt @@ -6,6 +6,7 @@ import org.jetbrains.kotlin.model.KPackage import org.jetbrains.kotlin.template.TextTemplate import org.jetbrains.kotlin.model.KFunction import java.util.Collection +import org.jetbrains.kotlin.model.KProperty abstract class KDocTemplate() : TextTemplate() { fun rootHref(pkg: KPackage): String { @@ -23,11 +24,6 @@ abstract class KDocTemplate() : TextTemplate() { return "${rootHref(c.pkg)}${c.nameAsPath}.html$postfix" } - fun extensionsHref(pkg: KPackage, c: KClass): String { - // is inside the pkg so no need to use it... - return "${c.nameAsPath}-extensions.html" - } - fun href(f: KFunction): String { return if (f.owner is KClass) { "${href(f.owner)}#${f.link}" @@ -36,6 +32,19 @@ abstract class KDocTemplate() : TextTemplate() { } } + fun href(f: KProperty): String { + return if (f.owner is KClass) { + "${href(f.owner)}#${f.link}" + } else { + "package-summary.html#${f.link}" + } + } + + fun extensionsHref(pkg: KPackage, c: KClass): String { + // is inside the pkg so no need to use it... + return "${c.nameAsPath}-extensions.html" + } + fun sourceHref(f: KFunction): String { return if (f.owner is KClass) { "${rootHref(f.owner.pkg)}src-html/${f.owner.simpleName}.html#line.${f.sourceLine}" diff --git a/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/PackageTemplateSupport.kt b/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/PackageTemplateSupport.kt index de60f6ba6ab..77a96a41e2e 100644 --- a/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/PackageTemplateSupport.kt +++ b/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/PackageTemplateSupport.kt @@ -10,6 +10,7 @@ import org.jetbrains.kotlin.model.KPackage import org.jetbrains.kotlin.model.KClass import org.jetbrains.kotlin.model.KFunction import org.jetbrains.kotlin.model.KAnnotation +import org.jetbrains.kotlin.model.KProperty abstract class PackageTemplateSupport(open val pkg: KPackage) : KDocTemplate() { @@ -19,7 +20,7 @@ abstract class PackageTemplateSupport(open val pkg: KPackage) : KDocTemplate() { fun printFunctionSummary(functions: Collection): Unit { if (functions.notEmpty()) { - println(""" + println(""" @@ -38,27 +39,6 @@ abstract class PackageTemplateSupport(open val pkg: KPackage) : KDocTemplate() { } } - fun printFunctionDetail(functions: Collection): Unit { - if (functions.notEmpty()) { - println(""" - - - - -
- - - -
- Method Detail
- """) - - for (f in functions) { - printFunctionDetail(f) - } - } - } - fun printFunctionSummary(method: KFunction): Unit { val deprecated = if (method.deprecated) "Deprecated." else "" print(""" @@ -88,19 +68,40 @@ abstract class PackageTemplateSupport(open val pkg: KPackage) : KDocTemplate() { println("") } - fun printFunctionDetail(method: KFunction): Unit { - println("

") - println("${method.name}

") + fun printFunctionDetail(functions: Collection): Unit { + if (functions.notEmpty()) { + println(""" + + + + + + + + +
+ Method Detail
+ """) + + for (f in functions) { + printFunctionDetail(f) + } + } + } + + fun printFunctionDetail(function: KFunction): Unit { + println("

") + println("${function.name}

") println("
")
         println("")
-        printAnnotations(method.annotations)
-        print("${method.modifiers.join(" ")} ")
+        printAnnotations(function.annotations)
+        print("${function.modifiers.join(" ")} ")
 
-        printTypeParameters(method)
-        print(link(method.returnType))
-        print(" ${method.name}")
-        printParameters(method)
-        val exlist = method.exceptions
+        printTypeParameters(function)
+        print(link(function.returnType))
+        print(" ${function.name}")
+        printParameters(function)
+        val exlist = function.exceptions
         var first = true
         if (!exlist.isEmpty()) {
             println("                                throws ");
@@ -129,6 +130,59 @@ abstract class PackageTemplateSupport(open val pkg: KPackage) : KDocTemplate() {
         println("
")
     }
 
+    fun printPropertySummary(properties: Collection): Unit {
+        if (properties.notEmpty()) {
+            println("""
+
+
+
+
+
+""")
+
+            for (f in properties) {
+                printPropertySummary(f)
+            }
+            println("""

+Property Summary

+ 
+

+""")
+        }
+    }
+
+    fun printPropertySummary(property: KProperty): Unit {
+        val deprecated = if (property.deprecated) "Deprecated." else ""
+        print("""
+
+""")
+        /*
+        if (!property.typeParameters.isEmpty()) {
+            println("""
+            
+            
+
+

+            """)
+            printTypeParameters(property)
+            println("
")
+            print(link(property.returnType))
+            println("""
""")
+        } else {
+            print(link(property.returnType))
+        }
+        */
+        print(link(property.returnType))
+        println("")
+        print("${property.name}")
+        //printParameters(property)
+        println("")
+        println("")
+        println("
")
+        println("          ${deprecated} ${property.detailedDescription}")
+        println("")
+    }
+
     fun printTypeParameters(method: KFunction): Unit {
         val typeParameters = method.typeParameters
         if (!typeParameters.isEmpty()) {
diff --git a/kdoc/src/main/kotlin/org/jetbrains/kotlin/model/KotlinModel.kt b/kdoc/src/main/kotlin/org/jetbrains/kotlin/model/KotlinModel.kt
index 20d944e54f6..1fb183c43f5 100644
--- a/kdoc/src/main/kotlin/org/jetbrains/kotlin/model/KotlinModel.kt
+++ b/kdoc/src/main/kotlin/org/jetbrains/kotlin/model/KotlinModel.kt
@@ -143,17 +143,21 @@ class KModel(var context: BindingContext, var title: String = "Documentation", v
         try {
             val descriptors = scope.getAllDescriptors()
             for (descriptor in descriptors) {
-                if (descriptor is CallableDescriptor) {
+                if (descriptor is PropertyDescriptor) {
+                    if (owner is KClass) {
+                        val name = descriptor.getName()
+                        println("Found Property on owner: $owner with name: $name")
+                        val returnType = getClass(descriptor.getReturnType())
+                        if (returnType != null) {
+                            val property = KProperty(owner, descriptor, name, returnType)
+                            owner.properties.add(property)
+                        }
+                    }
+                } else if (descriptor is CallableDescriptor) {
                     val function = createFunction(owner, descriptor)
                     if (function != null) {
                         list.add(function)
                     }
-                } else if (descriptor is PropertyDescriptor) {
-                    if (owner is KClass) {
-                        val name = descriptor.getName()
-                        val property = KProperty(descriptor, name)
-                        owner.properties.add(property)
-                    }
                 }
             }
         } catch (e: Throwable) {
@@ -261,7 +265,9 @@ abstract class KAnnotated {
     public open var description: String = ""
 
     public open var detailedDescription: String = ""
-        get() = if ($detailedDescription.notEmpty()) $detailedDescription else description
+    get() = if ($detailedDescription.notEmpty()) $detailedDescription else description
+
+    public open var deprecated: Boolean = false
 }
 
 class KPackage(val model: KModel, val descriptor: NamespaceDescriptor,
@@ -401,7 +407,6 @@ class KClass(val pkg: KPackage, val descriptor: ClassDescriptor,
 
 class KFunction(val owner: KClassOrPackage, val name: String,
         var returnType: KClass,
-        var deprecated: Boolean = false,
         var extensionClass: KClass? = null,
         var modifiers: List = arrayList(),
         var typeParameters: List = arrayList(),
@@ -422,7 +427,6 @@ class KFunction(val owner: KClassOrPackage, val name: String,
 
     fun toString() = "fun ($name)"
 
-    /** TODO generate a link with the argument type names */
     public val link: String = "$name($parameterTypeText)"
 
     /** Returns a list of generic type parameter names kinds like "A, I" */
@@ -440,10 +444,13 @@ class KFunction(val owner: KClassOrPackage, val name: String,
     }
 }
 
-class KProperty(var descriptor: PropertyDescriptor, var name: String) : KAnnotated(), Comparable {
+class KProperty(val owner: KClassOrPackage, val descriptor: PropertyDescriptor, val name: String,
+        val returnType: KClass) : KAnnotated(), Comparable {
 
     override fun compareTo(other: KProperty): Int = name.compareTo(other.name)
 
+    public val link: String = "$name"
+
     fun equals(other: KFunction) = name == other.name
 
     fun toString() = "property $name}"