From 6806954cb827bf73aff8c6d6a5847beb5f82829e Mon Sep 17 00:00:00 2001 From: James Strachan Date: Sat, 14 Apr 2012 05:43:15 +0100 Subject: [PATCH] kdoc improvements: added discovery of ReadMe.md or ReadMe.html files in a package source directory, so we can auto-discover documentation like this https://github.com/JetBrains/kotlin/blob/master/libraries/stdlib/src/kotlin/ReadMe.md and fixed a regression where we could not find the KPackage of a descriptor with changes to the AST and fixed up some bad links to external classes --- .../org/jetbrains/kotlin/doc/KDocConfig.kt | 2 +- .../jetbrains/kotlin/doc/model/KotlinModel.kt | 27 +++++++++---------- .../kotlin/doc/templates/KDocTemplate.kt | 14 +++++----- 3 files changed, 21 insertions(+), 22 deletions(-) diff --git a/libraries/tools/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/KDocConfig.kt b/libraries/tools/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/KDocConfig.kt index 586b7463fd6..8c0501e69c2 100644 --- a/libraries/tools/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/KDocConfig.kt +++ b/libraries/tools/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/KDocConfig.kt @@ -91,7 +91,7 @@ class KDocConfig() { /** * Resolves a link to the given class name */ - fun resolveLink(packageName: String): String { + fun resolveLink(packageName: String, warn: Boolean = true): String { for (e in packagePrefixToUrls) { val p = e.key val url = e.value diff --git a/libraries/tools/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/model/KotlinModel.kt b/libraries/tools/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/model/KotlinModel.kt index 99cd26205b7..80780cc4051 100644 --- a/libraries/tools/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/model/KotlinModel.kt +++ b/libraries/tools/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/model/KotlinModel.kt @@ -270,6 +270,7 @@ class KModel(var context: BindingContext, val config: KDocConfig) { val scope = descriptor.getMemberScope() addFunctions(pkg, scope) pkg.local = isLocal(descriptor) + pkg.useExternalLink = pkg.model.config.resolveLink(pkg.name, false).notEmpty() if (pkg.wikiDescription.isEmpty()) { // lets try find a custom doc @@ -872,7 +873,18 @@ abstract class KNamed(val name: String, model: KModel, declarationDescriptor: De class KPackage(model: KModel, val descriptor: NamespaceDescriptor, val name: String, - var local: Boolean = false): KClassOrPackage(model, descriptor), Comparable { + var local: Boolean = false, + var useExternalLink: Boolean = false): KClassOrPackage(model, descriptor), Comparable { + + + // TODO generates java.lang.NoSuchMethodError: kotlin.util.namespace.hashMap(Ljet/TypeInfo;Ljet/TypeInfo;)Ljava/util/HashMap; + //val classes = sortedMap() + public val classMap: SortedMap = TreeMap() + + public val classes: Collection + get() = classMap.values().sure().filter{ it.isApi() } + + public val annotations: Collection = ArrayList() public override fun compareTo(other: KPackage): Int = name.compareTo(other.name) @@ -930,7 +942,6 @@ class KPackage(model: KModel, val descriptor: NamespaceDescriptor, return if (answer.length == 0) "" else answer + "/" } - override fun description(template: KDocTemplate): String { // lets see if we can find a custom summary val text = model.config.packageSummaryText[name] @@ -940,17 +951,6 @@ class KPackage(model: KModel, val descriptor: NamespaceDescriptor, super.description(template) } - - - // TODO generates java.lang.NoSuchMethodError: kotlin.util.namespace.hashMap(Ljet/TypeInfo;Ljet/TypeInfo;)Ljava/util/HashMap; - //val classes = sortedMap() - public val classMap: SortedMap = TreeMap() - - public val classes: Collection - get() = classMap.values().sure().filter{ it.isApi() } - - public val annotations: Collection = ArrayList() - fun qualifiedName(simpleName: String): String { return if (name.length() > 0) { "${name}.${simpleName}" @@ -959,7 +959,6 @@ class KPackage(model: KModel, val descriptor: NamespaceDescriptor, } } - fun previous(pkg: KClass): KClass? { // TODO return null diff --git a/libraries/tools/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/KDocTemplate.kt b/libraries/tools/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/KDocTemplate.kt index e71a7d2cbf2..c615ab6cd6c 100644 --- a/libraries/tools/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/KDocTemplate.kt +++ b/libraries/tools/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/KDocTemplate.kt @@ -14,7 +14,7 @@ import java.util.List abstract class KDocTemplate() : TextTemplate() { open fun rootHref(pkg: KPackage): String { - return if (pkg.local) + return if (!pkg.useExternalLink) relativePrefix() else pkg.model.config.resolveLink(pkg.name) @@ -24,7 +24,7 @@ abstract class KDocTemplate() : TextTemplate() { = "${rootHref(p)}${p.nameAsPath}/package-summary.html" open fun href(c: KClass): String { - val postfix = if (c.pkg.local) "" else "?is-external=true" + val postfix = if (!c.pkg.useExternalLink) "" else "?is-external=true" return "${rootHref(c.pkg)}${c.nameAsPath}.html$postfix" } @@ -58,7 +58,7 @@ abstract class KDocTemplate() : TextTemplate() { return klass.sourceLink() } else { val pkg = klass.pkg - return if (pkg.local) { + return if (!pkg.useExternalLink) { "${pkg.nameAsRelativePath}src-html/${klass.nameAsPath}.html#line.${klass.sourceLine}" } else { href(klass) @@ -72,13 +72,13 @@ abstract class KDocTemplate() : TextTemplate() { val owner = f.owner return if (owner is KClass) { val pkg = owner.pkg - if (pkg.local) { + if (!pkg.useExternalLink) { "${rootHref(pkg)}src-html/${owner.simpleName}.html#line.${f.sourceLine}" } else { href(f) } } else if (owner is KPackage) { - if (owner.local) { + if (!owner.useExternalLink) { // TODO how to find the function in a package??? "${rootHref(owner)}src-html/namespace.html#line.${f.sourceLine}" } else { @@ -95,13 +95,13 @@ abstract class KDocTemplate() : TextTemplate() { val owner = f.owner return if (owner is KClass) { val pkg = owner.pkg - if (pkg.local) { + if (!pkg.useExternalLink) { "${rootHref(pkg)}src-html/${owner.simpleName}.html#line.${f.sourceLine}" } else { href(f) } } else if (owner is KPackage) { - if (owner.local) { + if (!owner.useExternalLink) { // TODO how to find the function in a package??? "${rootHref(owner)}src-html/namespace.html#line.${f.sourceLine}" } else {