From d83b76b7a75ba08006048a7dd2a788cf9795e00f Mon Sep 17 00:00:00 2001 From: James Strachan Date: Fri, 13 Apr 2012 17:43:54 +0100 Subject: [PATCH] kdoc improvements: allow package summaries, package API doc URLs and documentation files to be specified so we can better describe package, reuse documentation for them or link to external packages. #KT-1463 Fixed --- libraries/docs/apidoc/pom.xml | 20 ++++++++++ libraries/kotlin-swing/ReadMe.md | 1 + .../jetbrains/kotlin/maven/doc/KDocMojo.java | 35 +++++++++++++++++ .../org/jetbrains/kotlin/doc/KDocConfig.kt | 14 ++++++- .../jetbrains/kotlin/doc/model/KotlinModel.kt | 39 ++++++++++++++++++- .../doc/templates/PackageSummaryTemplate.kt | 6 ++- 6 files changed, 111 insertions(+), 4 deletions(-) diff --git a/libraries/docs/apidoc/pom.xml b/libraries/docs/apidoc/pom.xml index fe237a8717f..b36fb318c9d 100644 --- a/libraries/docs/apidoc/pom.xml +++ b/libraries/docs/apidoc/pom.xml @@ -49,9 +49,29 @@ jet junit org + kotlin.support + kotlin.properties https://github.com/JetBrains/kotlin/tree/master ${project-root} + + ${project-root}/libraries/kotlin-swing/ReadMe.md + + + Core API + Functions for working with Java Beans + Concurrent programing API + Functions for working with the W3C DOM + IO API for working with files and streams + Functions for working with SQL databases via JDBC (in kotlin-jdbc module) + Mathematics API + API for defining compilation units + Functions for treating nullable types as composable collections of zero or one element + Swing API (in kotlin-swing module) + Text processing API + Functions for writing tests (in kunit module) + Utility functions + diff --git a/libraries/kotlin-swing/ReadMe.md b/libraries/kotlin-swing/ReadMe.md index 35b6b5639d4..6fb1a0aa3c2 100644 --- a/libraries/kotlin-swing/ReadMe.md +++ b/libraries/kotlin-swing/ReadMe.md @@ -4,6 +4,7 @@ The Kotlin Swing library provides some helper functions and extensions for creat To try the sample run + cd kotlin/libraries/kotlin-swing mvn test -Pui Or browse the [source of the sample](https://github.com/JetBrains/kotlin/blob/master/libraries/kotlin-swing/src/test/kotlin/test/kotlin/swing/SwingSample.kt) diff --git a/libraries/tools/kdoc-maven-plugin/src/main/java/org/jetbrains/kotlin/maven/doc/KDocMojo.java b/libraries/tools/kdoc-maven-plugin/src/main/java/org/jetbrains/kotlin/maven/doc/KDocMojo.java index 287009860d2..1409871d85c 100644 --- a/libraries/tools/kdoc-maven-plugin/src/main/java/org/jetbrains/kotlin/maven/doc/KDocMojo.java +++ b/libraries/tools/kdoc-maven-plugin/src/main/java/org/jetbrains/kotlin/maven/doc/KDocMojo.java @@ -25,6 +25,7 @@ import org.jetbrains.kotlin.doc.KDocConfig; import org.jetbrains.kotlin.maven.KotlinCompileMojoBase; import java.util.List; +import java.util.Map; /** * Generates API docs documentation for kotlin sources @@ -139,6 +140,29 @@ public class KDocMojo extends KotlinCompileMojoBase { */ private boolean warnNoComments; + /** + * A Map of package name to file names for the description of packages. + * This allows you to refer to ReadMe.md files in your project root directory which will then be included in the API Doc. + * For packages which are not configured, KDoc will look for package.html or package.md files in the source directory + * + * @parameter expression="${packageDescriptionFiles}" + */ + private Map packageDescriptionFiles; + + /** + * A Map of package name prefixxes to HTTP URLs so we can link the API docs to external packages + * + * @parameter expression="${packagePrefixToUrls}" + */ + private Map packagePrefixToUrls; + + /** + * A Map of package name to summary text used in the package overview tables to give a brief summary for each package + * + * @parameter expression="${packagePrefixToUrls}" + */ + private Map packageSummaryText; + @Override protected KotlinCompiler createCompiler() { return new KDocCompiler(); @@ -160,6 +184,15 @@ public class KDocMojo extends KotlinCompileMojoBase { if (ignorePackages != null) { docConfig.getIgnorePackages().addAll(ignorePackages); } + if (packageDescriptionFiles != null) { + docConfig.getPackageDescriptionFiles().putAll(packageDescriptionFiles); + } + if (packagePrefixToUrls != null) { + docConfig.getPackagePrefixToUrls().putAll(packagePrefixToUrls); + } + if (packageSummaryText != null) { + docConfig.getPackageSummaryText().putAll(packageSummaryText); + } docConfig.setIncludeProtected(includeProtected); docConfig.setTitle(title); docConfig.setVersion(version); @@ -172,6 +205,8 @@ public class KDocMojo extends KotlinCompileMojoBase { getLog().info("sources: " + sources); getLog().info("sourceRootHref: " + sourceRootHref); getLog().info("projectRootDir: " + projectRootDir); + getLog().info("packageDescriptionFiles: " + packageDescriptionFiles); + getLog().info("packagePrefixToUrls: " + packagePrefixToUrls); getLog().info("API docs ignore packages: " + ignorePackages); } else { 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 f968d1b860d..586b7463fd6 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 @@ -26,7 +26,8 @@ class KDocConfig() { public var version: String = "SNAPSHOT" /** - * Returns a map of the package prefix to the URLs to use to link to it in the documentation + * Returns a map of the package prefix to the HTML URL for the root of the apidoc using javadoc/kdoc style + * directory layouts so that this API doc report can link to external packages */ public val packagePrefixToUrls: Map = TreeMap(LongestFirstStringComparator()) @@ -51,6 +52,17 @@ class KDocConfig() { */ public var projectRootDir: String? = null + /** + * A map of package name to html or markdown files used to describe the package. If none is + * speciied we will look for a package.html or package.md file in the source tree + */ + public var packageDescriptionFiles: Map = HashMap() + + /** + * A map of package name to summary text used in the package overviews + */ + public var packageSummaryText: Map = HashMap() + /** * Returns true if protected functions and properties should be documented */ 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 69390a01843..ff6c94b5b04 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 @@ -79,6 +79,10 @@ fun warning(message: String) { println("Warning: $message") } +fun info(message: String) { + // println("info: $message") +} + // TODO for some reason the SortedMap causes kotlin to freak out a little :) fun inheritedExtensionFunctions(functions: Collection): Map> { //fun inheritedExtensionFunctions(functions: Collection): SortedMap> { @@ -259,6 +263,30 @@ class KModel(var context: BindingContext, val config: KDocConfig) { val scope = descriptor.getMemberScope() addFunctions(pkg, scope) pkg.local = isLocal(descriptor) + + if (pkg.wikiDescription.isEmpty()) { + // lets try find a custom doc + var file = config.packageDescriptionFiles[name] + if (file == null) { + // lets try find the package.html or package.md file + val srcPath = pkg.filePath() + if (srcPath != null) { + val srcFile = File(srcPath) + val dir = if (srcFile.isDirectory()) srcFile else srcFile.getParentFile() + val f = arrayList(File(dir, "package.html"), File(dir, "package.md")).find{ it.exists() } + if (f != null) file = f.getCanonicalPath() else { + info("package $name has no package.(html|md) in $dir") + } + } + } + if (file != null) { + try { + pkg.wikiDescription = File(file).readText() + } catch (e: Throwable) { + warning("Failed to load package $name documentation file $file. Reason $e") + } + } + } } return pkg; } @@ -742,7 +770,7 @@ abstract class KAnnotated(val model: KModel, val declarationDescriptor: Declarat public open var deprecated: Boolean = false - fun description(template: KDocTemplate): String { + open fun description(template: KDocTemplate): String { val detailedText = detailedDescription(template) val idx = detailedText.indexOf("

") return if (idx > 0) { @@ -766,7 +794,7 @@ abstract class KAnnotated(val model: KModel, val declarationDescriptor: Declarat } fun sourceLink(): String { - val file = model.filePath(declarationDescriptor) + val file = filePath() if (file != null) { // lets remove the root project directory val rootDir = model.projectRootDir() @@ -778,6 +806,8 @@ abstract class KAnnotated(val model: KModel, val declarationDescriptor: Declarat return "" } + fun filePath(): String? = model.filePath(declarationDescriptor) + protected fun sourceLinkFor(filePath: String, lineLinkText: String = "#L"): String { val root = model.config.sourceRootHref!! val cleanRoot = root.trimTrailing("/") @@ -862,6 +892,11 @@ class KPackage(model: KModel, val descriptor: NamespaceDescriptor, } + override fun description(template: KDocTemplate): String { + // lets see if we can find a custom summary + val text = model.config.packageSummaryText[name] + return if (text != null) text else super.description(template) + } diff --git a/libraries/tools/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/PackageSummaryTemplate.kt b/libraries/tools/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/PackageSummaryTemplate.kt index b880e16a3ca..231c87a2eb1 100644 --- a/libraries/tools/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/PackageSummaryTemplate.kt +++ b/libraries/tools/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/PackageSummaryTemplate.kt @@ -192,7 +192,7 @@ ${pkg.detailedDescription(this)} printNextPrevPackages() println(""" -) FRAMES   + FRAMES    NO FRAMES