kdoc improvements: allow package summaries, package API doc URLs and...

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

@@ -49,9 +49,29 @@
                         <ignorePackage>jet</ignorePackage>
                         <ignorePackage>junit</ignorePackage>
                         <ignorePackage>org</ignorePackage>
+                        <ignorePackage>kotlin.support</ignorePackage>
+                        <ignorePackage>kotlin.properties</ignorePackage>
                     </ignorePackages>
                     <sourceRootHref>https://github.com/JetBrains/kotlin/tree/master</sourceRootHref>
                     <projectRootDir>${project-root}</projectRootDir>
+                    <packageDescriptionFiles>
+                        <kotlin.swing>${project-root}/libraries/kotlin-swing/ReadMe.md</kotlin.swing>
+                    </packageDescriptionFiles>
+                    <packageSummaryText>
+                        <kotlin>Core API</kotlin>
+                        <kotlin.beans>Functions for working with Java Beans</kotlin.beans>
+                        <kotlin.concurrent>Concurrent programing API</kotlin.concurrent>
+                        <kotlin.dom>Functions for working with the W3C DOM</kotlin.dom>
+                        <kotlin.io>IO API for working with files and streams</kotlin.io>
+                        <kotlin.jdbc>Functions for working with SQL databases via JDBC (in kotlin-jdbc module)</kotlin.jdbc>
+                        <kotlin.math>Mathematics API</kotlin.math>
+                        <kotlin.modules>API for defining compilation units</kotlin.modules>
+                        <kotlin.nullable>Functions for treating nullable types as composable collections of zero or one element</kotlin.nullable>
+                        <kotlin.swing>Swing API (in kotlin-swing module)</kotlin.swing>
+                        <kotlin.template>Text processing API</kotlin.template>
+                        <kotlin.test>Functions for writing tests (in kunit module)</kotlin.test>
+                        <kotlin.util>Utility functions</kotlin.util>
+                    </packageSummaryText>
                 </configuration>
 
                 <executions>

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)

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<String,String> 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<String,String> 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<String, String> 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 {

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<String, String> = TreeMap<String, String>(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<String,String> = HashMap<String,String>()
+
+    /**
+     * A map of package name to summary text used in the package overviews
+     */
+    public var packageSummaryText: Map<String,String> = HashMap<String,String>()
+
     /**
     * Returns true if protected functions and properties should be documented
     */

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<KFunction>): Map<KClass, SortedSet<KFunction>> {
     //fun inheritedExtensionFunctions(functions: Collection<KFunction>): SortedMap<KClass, SortedSet<KFunction>> {
@@ -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("</p>")
         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<KClassOrPackage>.description(template)
+    }
 
 
 

libraries/tools/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/PackageSummaryTemplate.kt

@@ -192,7 +192,7 @@ ${pkg.detailedDescription(this)}
         printNextPrevPackages()
 
         println("""<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
-)  <A HREF="${pkg.nameAsRelativePath}index.html?${pkg.nameAsPath}/package-summary.html" target="_top"><B>FRAMES</B></A>  &nbsp;
+  <A HREF="${pkg.nameAsRelativePath}index.html?${pkg.nameAsPath}/package-summary.html" target="_top"><B>FRAMES</B></A>  &nbsp;
 &nbsp;<A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A>  &nbsp;
 &nbsp;<SCRIPT type="text/javascript">
   <!--
@@ -306,10 +306,14 @@ Copyright &#169; 2010-2012. All Rights Reserved.
         val prev = model.previous(pkg)
         if (prev != null) {
             println("""&nbsp;<A HREF="${prev.nameAsRelativePath}${prev.nameAsPath}/package-summary.html"><B>PREV PACKAGE</B></A>&nbsp;""")
+        } else {
+            println("""&nbsp;PREV PACKAGE&nbsp;""" )
         }
         val next = model.next(pkg)
         if (next != null) {
             println("""&nbsp;<A HREF="${next.nameAsRelativePath}${next.nameAsPath}/package-summary.html"><B>NEXT PACKAGE</B></A>""")
+        } else {
+            println("""&nbsp;NEXT PACKAGE""" )
         }
         println("""</FONT></TD>""")