refactored the kdoc model to be in the kotlin.doc package, added a KDocConfig to represent the title and package prefixes -> URL links and provided some sensible out of the box defaults so we can link to external classes now in kdoc for KT-1463

2012-03-06 10:14:09 +00:00
parent ccaffd8165
commit 8152749caf
19 changed files with 174 additions and 74 deletions
@@ -1,6 +1,6 @@
 package org.jetbrains.kotlin.doc

-import org.jetbrains.kotlin.model.KModel
+import org.jetbrains.kotlin.doc.model.KModel
 import java.io.File

 /**
@@ -5,7 +5,7 @@ import kotlin.util.*

 import org.jetbrains.kotlin.doc.templates.*
 import org.jetbrains.kotlin.template.TextTemplate
-import org.jetbrains.kotlin.model.*
+import org.jetbrains.kotlin.doc.model.*

 import java.io.File
 import java.util.List
@@ -5,7 +5,7 @@ import kotlin.util.*

 import org.jetbrains.kotlin.doc.templates.*
 import org.jetbrains.kotlin.template.TextTemplate
-import org.jetbrains.kotlin.model.*
+import org.jetbrains.kotlin.doc.model.*

 import java.io.File
 import java.util.List
@@ -0,0 +1,92 @@
+package org.jetbrains.kotlin.doc
+
+import kotlin.*
+import kotlin.util.*
+import java.util.*
+
+/**
+ * The configuration used with KDoc
+ */
+class KDocConfig() {
+
+    /**
+     * Returns the name of the documentation set
+     */
+    public var title: String = "Documentation"
+
+    /**
+     * Returns a map of the package prefix to the URLs to use to link to it in the documentation
+     */
+    public val packagePrefixToUrls: Map<String, String> = TreeMap<String, String>(LongestFirstStringComparator())
+
+    /**
+    * Returns true if a warning should be generated if there are no comments
+    * on documented function or property
+    */
+    public var warnNoComments: Boolean = true
+
+    /**
+    * Returns true if protected functions and properties should be documented
+    */
+    public var includeProtected: Boolean = true
+
+    {
+        // TODO replace with hashMap(...) helper function?
+
+        // add some common defaults
+        addPackageLink("http://docs.oracle.com/javase/6/docs/api/", "java", "org.w3c.dom", "org.xml.sax", "org.omg", "org.ietf.jgss")
+        addPackageLink("http://kentbeck.github.com/junit/javadoc/latest/", "org.junit", "junit")
+    }
+
+    /**
+     * Returns a set of all the package which have been warned that were missing an external URL
+     */
+    public val missingPackageUrls: Set<String> = TreeSet<String>()
+
+    /**
+     * Adds one or more package prefixes to the given javadoc URL
+     */
+    fun addPackageLink(url: String, vararg packagePrefixes: String): Unit {
+        for (p in packagePrefixes) {
+            packagePrefixToUrls.put(p, url)
+        }
+    }
+
+    /**
+     * Resolves a link to the given class name
+     */
+    fun resolveLink(packageName: String): String {
+        // TODO should be able to do something like
+        // for (e in packageUrls.filterNulls()) {
+        val entrySet = packagePrefixToUrls.entrySet()
+        if (entrySet != null) {
+            for (e in entrySet) {
+                val p = e?.getKey()
+                val url = e?.getValue()
+                if (p != null && url != null) {
+                    if (packageName.startsWith(p)) {
+                        return url
+                    }
+                }
+            }
+        }
+        if (missingPackageUrls.add(packageName)) {
+            println("Warning: could not find external link to package: $packageName")
+        }
+        return ""
+    }
+}
+
+protected class LongestFirstStringComparator() : Comparator<String> {
+    override fun compare(s1: String, s2: String): Int {
+        var answer = s1.length() - s2.length()
+        if (answer == 0) {
+            answer = s1.compareTo(s2)
+        }
+        return answer
+    }
+
+    override fun equals(obj : Any?) : Boolean {
+        return obj is LongestFirstStringComparator
+    }
+}
@@ -1,11 +1,11 @@
-package org.jetbrains.kotlin.model
+package org.jetbrains.kotlin.doc.model

 import kotlin.*
 import kotlin.util.*

+import org.jetbrains.kotlin.doc.KDocConfig
 import org.jetbrains.kotlin.doc.templates.*
 import org.jetbrains.kotlin.template.TextTemplate
-import org.jetbrains.kotlin.model.*

 import java.io.File
 import java.util.List
@@ -35,9 +35,11 @@ import org.jetbrains.jet.lang.resolve.BindingContextUtils
 /** Base class for any compiler plugin which needs to process a KModel */
 abstract class KModelCompilerPlugin : CompilerPlugin {

+    public open var config: KDocConfig = KDocConfig()
+
    override fun processFiles(context: BindingContext?, sources: List<JetFile?>?) {
        if (context != null && sources != null) {
-            val model = KModel(context)
+            val model = KModel(context, config)
            model.load(sources)

            processModel(model)
@@ -1,9 +1,10 @@
-package org.jetbrains.kotlin.model
+package org.jetbrains.kotlin.doc.model

-import java.lang.String
 import kotlin.*
 import kotlin.util.*

+import org.jetbrains.kotlin.doc.KDocConfig
+
 import java.util.*
 import org.jetbrains.jet.lang.descriptors.ClassDescriptor
 import org.jetbrains.jet.lang.descriptors.NamespaceDescriptor
@@ -125,7 +126,7 @@ abstract class KClassOrPackage : KAnnotated() {
    public open val properties: SortedSet<KProperty> = TreeSet<KProperty>()
 }

-class KModel(var context: BindingContext, var title: String = "Documentation", var version: String = "TODO") {
+class KModel(var context: BindingContext, val config: KDocConfig, var title: String = "Documentation", var version: String = "TODO") {
    // TODO generates java.lang.NoSuchMethodError: kotlin.util.namespace.hashMap(Ljet/TypeInfo;Ljet/TypeInfo;)Ljava/util/HashMap;
    //val packages = sortedMap<String,KPackage>()
    public val packageMap: SortedMap<String, KPackage> = TreeMap<String, KPackage>()
@@ -418,7 +419,7 @@ abstract class KNamed(val name: String) : KAnnotated(), Comparable<KNamed> {


 class KPackage(val model: KModel, val descriptor: NamespaceDescriptor,
-        val name: String, var external: Boolean = false,
+        val name: String,
        var local: Boolean = false) : KClassOrPackage(), Comparable<KPackage> {

    override fun compareTo(other: KPackage): Int = name.compareTo(other.name)
@@ -616,18 +617,6 @@ class KFunction(val descriptor: CallableDescriptor, val owner: KClassOrPackage,
    /** Returns a list of generic type parameter names kinds like "A, I" */
    public val typeParametersText: String
    get() = typeParameters.map{ it.name }.join(", ")
-
-    /** Returns a list of parameter value types */
-    /*
-    private var _parameterTypeText: String? = null
-    public val parameterTypeText: String
-    get() {
-        if (_parameterTypeText == null) {
-            _parameterTypeText = parameters.map{ it.aType.name }.join(", ")
-        }
-        return _parameterTypeText.sure()
-    }
-    */
 }

 class KProperty(val owner: KClassOrPackage, val descriptor: PropertyDescriptor, val name: String,
@@ -5,7 +5,7 @@ import org.jetbrains.kotlin.template.*
 import kotlin.io.*
 import kotlin.util.*
 import java.util.*
-import org.jetbrains.kotlin.model.KModel
+import org.jetbrains.kotlin.doc.model.KModel

 class AllClassesFrameTemplate(val model: KModel, val classAttributes: String = "") : KDocTemplate() {
    override fun render() {
@@ -5,12 +5,12 @@ import org.jetbrains.kotlin.template.*
 import kotlin.io.*
 import kotlin.util.*
 import java.util.*
-import org.jetbrains.kotlin.model.KModel
-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
+import org.jetbrains.kotlin.doc.model.KModel
+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.KAnnotation
+import org.jetbrains.kotlin.doc.model.KProperty

 class ClassExtensionsTemplate(m: KModel, p: KPackage, k: KClass,
        val functions: Collection<KFunction>, val properties: Collection<KProperty>) : ClassTemplate(m, p, k) {
@@ -27,7 +27,7 @@ ${pkg.name}</FONT>
 Extensions on ${klass.name}</H2>
 <DL>
 <DT>
-extension functions on class <A HREF="${pkg.nameAsRelativePath}src-html/${klass.nameAsPath}.html#line.${klass.sourceLine}"><B>${klass.name}</B></A><DT>
+extension functions on class <A HREF="${sourceHref(klass)}"><B>${klass.name}</B></A><DT>
 from package ${link(pkg)}
 </DL>
 </PRE>
@@ -5,11 +5,11 @@ import org.jetbrains.kotlin.template.*
 import kotlin.io.*
 import kotlin.util.*
 import java.util.*
-import org.jetbrains.kotlin.model.KModel
-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.doc.model.KModel
+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.KAnnotation

 open class ClassTemplate(open val model: KModel, pkg: KPackage, open val klass: KClass) : PackageTemplateSupport(pkg) {

@@ -184,7 +184,7 @@ Class ${klass.simpleName}</H2>
 <DL>
 <DT><PRE><FONT SIZE="-1">""")
        printAnnotations(klass.annotations)
-        print("""</FONT>public class <A HREF="${pkg.nameAsRelativePath}src-html/${klass.nameAsPath}.html#line.${klass.sourceLine}"><B>${klass.simpleName}</B></A><DT>""")
+        print("""</FONT>public class <A HREF="${sourceHref(klass)}"><B>${klass.simpleName}</B></A><DT>""")
        if (!klass.baseClasses.isEmpty()) {
            print("""extends """)
            for (bc in klass.baseClasses) {
@@ -5,7 +5,7 @@ import org.jetbrains.kotlin.template.*
 import kotlin.io.*
 import kotlin.util.*
 import java.util.*
-import org.jetbrains.kotlin.model.KModel
+import org.jetbrains.kotlin.doc.model.KModel

 class HelpDocTemplate(val model: KModel) : KDocTemplate() {
    override fun render() {
@@ -5,7 +5,7 @@ import org.jetbrains.kotlin.template.*
 import kotlin.io.*
 import kotlin.util.*
 import java.util.*
-import org.jetbrains.kotlin.model.KModel
+import org.jetbrains.kotlin.doc.model.KModel

 class IndexTemplate(val model: KModel) : KDocTemplate() {
  override fun render() {
@@ -2,29 +2,29 @@ package org.jetbrains.kotlin.doc.templates

 import kotlin.*
 import kotlin.util.*
-import org.jetbrains.kotlin.model.KClass
-import org.jetbrains.kotlin.model.KAnnotation
-import org.jetbrains.kotlin.model.KPackage
+import org.jetbrains.kotlin.doc.model.KClass
+import org.jetbrains.kotlin.doc.model.KAnnotation
+import org.jetbrains.kotlin.doc.model.KPackage
 import org.jetbrains.kotlin.template.TextTemplate
-import org.jetbrains.kotlin.model.KFunction
+import org.jetbrains.kotlin.doc.model.KFunction
 import java.util.Collection
-import org.jetbrains.kotlin.model.KProperty
-import org.jetbrains.kotlin.model.KType
+import org.jetbrains.kotlin.doc.model.KProperty
+import org.jetbrains.kotlin.doc.model.KType
 import java.util.List

 abstract class KDocTemplate() : TextTemplate() {
    open fun rootHref(pkg: KPackage): String {
-        return if (pkg.external) {
-            // TODO deal with external classes
-            ""
-        } else relativePrefix()
+        return if (pkg.local)
+            relativePrefix()
+        else
+            pkg.model.config.resolveLink(pkg.name)
    }

    open fun href(p: KPackage): String
-        = "${rootHref(p)}${p.nameAsPath}/package-summary.html"
+    = "${rootHref(p)}${p.nameAsPath}/package-summary.html"

    open fun href(c: KClass): String {
-        val postfix = if (c.pkg.external) "?is-external=true" else ""
+        val postfix = if (c.pkg.local) "" else "?is-external=true"
        return "${rootHref(c.pkg)}${c.nameAsPath}.html$postfix"
    }

@@ -53,13 +53,30 @@ abstract class KDocTemplate() : TextTemplate() {
        return "${extensionsHref(pkg, c)}#${f.link}"
    }

+    open fun sourceHref(klass: KClass): String {
+        val pkg = klass.pkg
+        return if (pkg.local) {
+            "${pkg.nameAsRelativePath}src-html/${klass.nameAsPath}.html#line.${klass.sourceLine}"
+        } else {
+            href(klass)
+        }
+    }
    open fun sourceHref(f: KFunction): String {
        val owner = f.owner
        return if (owner is KClass) {
-            "${rootHref(owner.pkg)}src-html/${owner.simpleName}.html#line.${f.sourceLine}"
+            val pkg = owner.pkg
+            if (pkg.local) {
+                "${rootHref(pkg)}src-html/${owner.simpleName}.html#line.${f.sourceLine}"
+            } else {
+                href(f)
+            }
        } else if (owner is KPackage) {
-            // TODO how to find the function in a package???
-            "${rootHref(owner)}src-html/namespace.html#line.${f.sourceLine}"
+            if (owner.local) {
+                // TODO how to find the function in a package???
+                "${rootHref(owner)}src-html/namespace.html#line.${f.sourceLine}"
+            } else {
+                href(owner)
+            }
        } else href(f)
    }

@@ -5,7 +5,7 @@ import org.jetbrains.kotlin.template.*
 import kotlin.io.*
 import kotlin.util.*
 import java.util.*
-import org.jetbrains.kotlin.model.KModel
+import org.jetbrains.kotlin.doc.model.KModel

 class OverviewFrameTemplate(val model: KModel) : KDocTemplate() {
    override fun render() {
@@ -5,7 +5,7 @@ import org.jetbrains.kotlin.template.*
 import kotlin.io.*
 import kotlin.util.*
 import java.util.*
-import org.jetbrains.kotlin.model.KModel
+import org.jetbrains.kotlin.doc.model.KModel

 class OverviewSummaryTemplate(val model: KModel) : KDocTemplate() {
    override fun render() {
@@ -5,7 +5,7 @@ import org.jetbrains.kotlin.template.*
 import kotlin.io.*
 import kotlin.util.*
 import java.util.*
-import org.jetbrains.kotlin.model.KModel
+import org.jetbrains.kotlin.doc.model.KModel

 class OverviewTreeTemplate(val model: KModel) : KDocTemplate() {
    override fun render() {
@@ -5,11 +5,11 @@ import org.jetbrains.kotlin.template.*
 import kotlin.io.*
 import kotlin.util.*
 import java.util.*
-import org.jetbrains.kotlin.model.KModel
-import org.jetbrains.kotlin.model.KPackage
-import org.jetbrains.kotlin.model.KClass
-import org.jetbrains.kotlin.model.KFunction
-import org.jetbrains.kotlin.model.extensionFunctions
+import org.jetbrains.kotlin.doc.model.KModel
+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

 class PackageFrameTemplate(val model: KModel, p: KPackage) : PackageTemplateSupport(p) {
    override fun render() {
@@ -5,7 +5,7 @@ import org.jetbrains.kotlin.template.*
 import kotlin.io.*
 import kotlin.util.*
 import java.util.*
-import org.jetbrains.kotlin.model.KModel
+import org.jetbrains.kotlin.doc.model.KModel

 class PackageListTemplate(val model: KModel) : KDocTemplate() {
  override fun render() {
@@ -5,11 +5,11 @@ import org.jetbrains.kotlin.template.*
 import kotlin.io.*
 import kotlin.util.*
 import java.util.*
-import org.jetbrains.kotlin.model.KModel
-import org.jetbrains.kotlin.model.KPackage
-import org.jetbrains.kotlin.model.KClass
-import org.jetbrains.kotlin.model.extensionFunctions
-import org.jetbrains.kotlin.model.inheritedExtensionFunctions
+import org.jetbrains.kotlin.doc.model.KModel
+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

 class PackageSummaryTemplate(val model: KModel, pkg: KPackage) : PackageTemplateSupport(pkg) {
    override fun render() {
@@ -5,13 +5,13 @@ import kotlin.io.*
 import kotlin.util.*
 import java.util.*
 import org.jetbrains.kotlin.template.*
-import org.jetbrains.kotlin.model.KModel
-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
-import org.jetbrains.kotlin.model.KTypeParameter
+import org.jetbrains.kotlin.doc.model.KModel
+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.KAnnotation
+import org.jetbrains.kotlin.doc.model.KProperty
+import org.jetbrains.kotlin.doc.model.KTypeParameter


 abstract class PackageTemplateSupport(open val pkg: KPackage) : KDocTemplate() {