Migrate to Dokka 0.10.1 (#385)

* Migrate to Dokka 0.10.1

* Upgrade other dependencies

* Fix dependency injection issue and cover it with a test

* Fix dependency injection issue and cover it with a test

* Adjust sample project

* Extend contribution with instructions for the Dokka test JAR

* Add note that Dokka only builds with JDK 8

* Review feedback and spell checker

Author: fbenz

.travis.yml

@@ -16,6 +16,9 @@ before_install:
 - mvn install:install-file -Dfile=lib/spring-restdocs-core-2.0.4.RELEASE-test.jar
   -DgroupId=org.springframework.restdocs -DartifactId=spring-restdocs-core -Dversion=2.0.4.RELEASE
   -Dpackaging=jar -Dclassifier=test
+- mvn install:install-file -Dfile=lib/dokka-core-0.10.1-tests.jar
+  -DgroupId=org.jetbrains.dokka -DartifactId=dokka-core -Dversion=0.10.1
+  -Dpackaging=jar -Dclassifier=test
 script:
 - mvn install -B -V
 - cd samples

lib/dokka-core-0.10.1-tests.jar

@@ -49,6 +49,7 @@
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
         <spring-restdocs.version>2.0.4.RELEASE</spring-restdocs.version>
+        <dokka.version>0.10.1</dokka.version>
     </properties>
 
     <build>

pom.xml

@@ -4,7 +4,7 @@ buildscript {
         springAutoRestDocsVersion = "2.0.9-SNAPSHOT"
         springRestDocsVersion = "2.0.4.RELEASE"
         springBootVersion = "2.2.6.RELEASE"
-        dokkaVersion = "0.9.18"
+        dokkaPluginVersion = "0.10.1"
     }
     repositories {
         jcenter()
@@ -17,7 +17,7 @@ buildscript {
         classpath "org.jetbrains.kotlin:kotlin-noarg:$kotlinVersion"
         classpath "org.springframework.boot:spring-boot-gradle-plugin:$springBootVersion"
         classpath "org.asciidoctor:asciidoctor-gradle-plugin:1.5.9.2"
-        classpath "org.jetbrains.dokka:dokka-gradle-plugin:$dokkaVersion"
+        classpath "org.jetbrains.dokka:dokka-gradle-plugin:$dokkaPluginVersion"
     }
 }
 
@@ -67,16 +67,8 @@ dependencies {
     testImplementation "com.jayway.jsonpath:json-path-assert"
     testImplementation "org.springframework.restdocs:spring-restdocs-core:$springRestDocsVersion"
     testImplementation "org.springframework.restdocs:spring-restdocs-mockmvc:$springRestDocsVersion"
-    // Java 11 fix for https://stackoverflow.com/questions/43574426/how-to-resolve-java-lang-noclassdeffounderror-javax-xml-bind-jaxbexception-in-j
-    testImplementation "javax.xml.bind:jaxb-api:2.3.0"
-    testImplementation "com.sun.xml.bind:jaxb-core:2.3.0.1"
-    testImplementation "com.sun.xml.bind:jaxb-impl:2.3.0.1"
-    testImplementation "javax.activation:activation:1.1.1"
-    if (JavaVersion.current() == JavaVersion.VERSION_1_8) {
-        testImplementation "capital.scalable:spring-auto-restdocs-json-doclet:$springAutoRestDocsVersion"
-    } else {
-        testImplementation "capital.scalable:spring-auto-restdocs-json-doclet-jdk9:$springAutoRestDocsVersion"
-    }}
+    dokkaRuntime "capital.scalable:spring-auto-restdocs-dokka-json:$springAutoRestDocsVersion"
+}
 
 test {
     systemProperty "org.springframework.restdocs.outputDir", snippetsDir
@@ -109,6 +101,8 @@ jar {
 dokka {
     outputFormat = "auto-restdocs-json"
     outputDirectory = javadocJsonDir
-    includeNonPublic = true
-    dokkaFatJar = "capital.scalable:spring-auto-restdocs-dokka-json:$springAutoRestDocsVersion"
+    configuration {
+        includeNonPublic = true
+        reportUndocumented = false
+    }
 }

samples/kotlin-webmvc/build.gradle

@@ -36,7 +36,7 @@
         <spring-restdocs.version>2.0.4.RELEASE</spring-restdocs.version>
         <spring-auto-restdocs.version>2.0.9-SNAPSHOT</spring-auto-restdocs.version>
         <kotlin.version>1.3.71</kotlin.version>
-        <dokka.version>0.9.18</dokka.version>
+        <dokka.version>0.10.1</dokka.version>
         <jsonDirectory>${project.build.directory}/generated-javadoc-json</jsonDirectory>
     </properties>
 
@@ -343,6 +343,7 @@
                             <prefix>capital.scalable.restdocs.example</prefix>
                             <!-- This feature only works inside packageOptions for the Maven plugin  -->
                             <includeNonPublic>true</includeNonPublic>
+                            <reportUndocumented>false</reportUndocumented>
                         </packageOptions>
                     </perPackageOptions>
                 </configuration>

samples/kotlin-webmvc/pom.xml

@@ -4,12 +4,12 @@
 [[contributing-building]]
 === Building from source
 
-[[contributing-installing-testjar]]
+[[contributing-installing-restdocs-testjar]]
 ==== Install Spring REST Docs test JAR
 
 The Spring REST Docs test JAR is not published via Maven, but this project relies on it.
 If you want to build this project yourself, you need to install the test JAR.
-The test JAR is located in the lib folder and can be installed as follow:
+The test JAR is located in the lib folder and can be installed as follows:
 
 .Bash
 [source,bash]
@@ -19,7 +19,22 @@ mvn install:install-file -Dfile=lib/spring-restdocs-core-${spring-restdocs.versi
     -Dversion=${spring-restdocs.version} -Dpackaging=test-jar -Dclassifier=test
 ----
 
-[[contributing-building-testjar]]
+[[contributing-installing-dokka-testjar]]
+==== Install Dokka Core test JAR
+
+Dokka publishes no test JAR, but the Spring Auto REST Docs Dokka extension uses their test utilities.
+If you want to build this project yourself, you need to install the test JAR.
+The test JAR is located in the lib folder and can be installed as follows:
+
+.Bash
+[source,bash]
+----
+mvn install:install-file -Dfile=lib/dokka-core-${dokka.version}-tests.jar \
+     -DgroupId=org.jetbrains.dokka -DartifactId=dokka-core -Dversion=${dokka.version} \
+     -Dpackaging=jar -Dclassifier=test
+----
+
+[[contributing-building-restdocs-testjar]]
 ==== Build Spring REST Docs test JAR
 
 Building the Spring REST Docs test JAR is not required to build the project,
@@ -57,6 +72,49 @@ Afterwards the test JAR is located at
 `spring-restdocs/spring-restdocs-core/build/libs/spring-restdocs-core-${spring-restdocs.version}-test.jar`
 and has to be installed with the Maven command shown in the section above.
 
+[[contributing-building-dokka-testjar]]
+==== Build Dokka Core test JAR
+
+Building the Dokka core test JAR is not required to build the project,
+but if you ever want to upgrade the version of Dokka in this project this step has to be done.
+
+We use version ${dokka.version} of Dokka in this example.
+
+Clone and checkout a specific version of Dokka:
+
+.Bash
+[source,bash]
+----
+git clone git@github.com:Kotlin/dokka.git
+cd dokka
+git checkout ${dokka.version}
+----
+
+Add the following snippet at the end of `core/build.gradle`:
+
+[source,groovy]
+----
+task testJar(type: Jar) {
+    classifier = 'tests'
+    from sourceSets.test.output
+}
+----
+
+To speed the build up and avoid test issues, once can reduce the list of sub-projects in
+`settings.gradle` to just `core` and `integration`.
+
+Make sure to use JDK 8 for the build.
+Create the test JAR by running the following command on the top-level:
+
+.Bash
+[source,bash]
+----
+./gradlew testJar
+----
+
+Afterwards the test JAR is located at
+`core/build/libs/core-${dokka.version}-SNAPSHOT-tests.jar`
+
 [[contributing-building-build]]
 ==== Build
 

spring-auto-restdocs-docs/contributing.adoc

@@ -18,11 +18,13 @@
 
     <properties>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-        <kotlin.version>1.3.41</kotlin.version>
+        <!-- Kotlin version bundled with Dokka -->
+        <kotlin.version>1.3.61</kotlin.version>
         <junit.version>4.12</junit.version>
-        <jackson.version>2.9.9</jackson.version>
-        <dokka.version>0.9.18</dokka.version>
+        <jackson.version>2.10.3</jackson.version>
         <kotlin.compiler.jvmTarget>1.8</kotlin.compiler.jvmTarget>
+        <maven.compiler.source>1.8</maven.compiler.source>
+        <maven.compiler.target>1.8</maven.compiler.target>
     </properties>
 
     <dependencies>
@@ -48,6 +50,13 @@
             <artifactId>dokka-fatjar</artifactId>
             <version>${dokka.version}</version>
         </dependency>
+        <dependency>
+            <groupId>org.jetbrains.dokka</groupId>
+            <artifactId>dokka-core</artifactId>
+            <version>${dokka.version}</version>
+            <classifier>test</classifier>
+            <scope>test</scope>
+        </dependency>
         <dependency>
             <groupId>com.fasterxml.jackson.core</groupId>
             <artifactId>jackson-core</artifactId>

spring-auto-restdocs-dokka-json/pom.xml

@@ -42,6 +42,7 @@ class JsonFormatDescriptor
     override fun configureOutput(binder: Binder): Unit = with(binder) {
         bind<Generator>() toType NodeLocationAwareGenerator::class
         bind<NodeLocationAwareGenerator>() toType JsonFileGenerator::class
+        bind(JsonFileGenerator::class.java) // https://github.com/google/guice/issues/847
         bind<LanguageService>() toType KotlinLanguageService::class
         bind<FormatService>() toType JsonFormatService::class
         bind<PackageListService>() toType DefaultPackageListService::class

spring-auto-restdocs-dokka-json/src/main/kotlin/capital/scalable/dokka/json/JsonFormatDescriptor.kt

@@ -22,13 +22,20 @@ package capital.scalable.dokka.json
 import com.intellij.openapi.util.io.FileUtil
 import org.jetbrains.dokka.DocumentationModule
 import org.jetbrains.dokka.DokkaConsoleLogger
+import org.jetbrains.dokka.Platform
 import org.jetbrains.dokka.contentRootFromPath
+import org.jetbrains.dokka.tests.ModelConfig
+import org.jetbrains.dokka.tests.verifyJavaModel
+import org.jetbrains.dokka.tests.verifyModel
+import org.jetbrains.kotlin.cli.common.config.KotlinSourceRoot
 import org.junit.Test
 import java.io.File
 import kotlin.test.assertTrue
 
 class JsonFileGeneratorTest {
 
+    private val analysisPlatform = Platform.common
+
     private val root: File = FileUtil.createTempDirectory("dokka-json", "file-generator-test")
 
     @Test
@@ -47,7 +54,12 @@ class JsonFileGeneratorTest {
 
     private fun verifyOutput(inputFile: String, verifier: (DocumentationModule) -> Unit) {
         verifyModel(
-            contentRootFromPath("testdata/$inputFile"),
+            ModelConfig(
+                roots = arrayOf(
+                    KotlinSourceRoot("testdata/$inputFile", false)
+                ),
+                analysisPlatform = analysisPlatform
+            ),
             verifier = verifier
         )
     }

spring-auto-restdocs-dokka-json/src/test/kotlin/capital/scalable/dokka/json/JsonFileGeneratorTest.kt

@@ -0,0 +1,117 @@
+/*-
+ * #%L
+ * Spring Auto REST Docs Dokka JSON
+ * %%
+ * Copyright (C) 2015 - 2020 Scalable Capital GmbH
+ * %%
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * #L%
+ */
+package capital.scalable.dokka.json
+
+import com.google.inject.Binder
+import com.google.inject.Guice
+import com.google.inject.Module
+import com.google.inject.name.Names
+import com.intellij.openapi.util.io.FileUtil
+import org.jetbrains.dokka.Content
+import org.jetbrains.dokka.DefaultPackageListService
+import org.jetbrains.dokka.DocumentationNode
+import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.DokkaConsoleLogger
+import org.jetbrains.dokka.DokkaGenerator
+import org.jetbrains.dokka.DokkaLogger
+import org.jetbrains.dokka.FormatService
+import org.jetbrains.dokka.Formats.FormatDescriptor
+import org.jetbrains.dokka.Generator
+import org.jetbrains.dokka.KotlinLanguageService
+import org.jetbrains.dokka.LanguageService
+import org.jetbrains.dokka.NodeKind
+import org.jetbrains.dokka.NodeLocationAwareGenerator
+import org.jetbrains.dokka.PackageListService
+import org.jetbrains.dokka.Platform
+import org.jetbrains.dokka.Utilities.DokkaRunModule
+import org.jetbrains.dokka.Utilities.ServiceLocator
+import org.junit.Test
+import java.io.File
+
+class JsonFormatIntegrationTest {
+
+    @Test
+    fun `Should load descriptor from properties file, bind and use it`() {
+        DokkaGenerator(DokkaConfigurationImpl(), DokkaConsoleLogger).generate()
+    }
+}
+
+data class SourceLinkDefinitionImpl(override val path: String,
+                                    override val url: String,
+                                    override val lineSuffix: String?) : DokkaConfiguration.SourceLinkDefinition {
+    companion object {
+        fun parseSourceLinkDefinition(srcLink: String): DokkaConfiguration.SourceLinkDefinition {
+            val (path, urlAndLine) = srcLink.split('=')
+            return SourceLinkDefinitionImpl(
+                File(path).canonicalPath,
+                urlAndLine.substringBefore("#"),
+                urlAndLine.substringAfter("#", "").let { if (it.isEmpty()) null else "#$it" })
+        }
+    }
+}
+
+class SourceRootImpl(path: String) : DokkaConfiguration.SourceRoot {
+    override val path: String = File(path).absolutePath
+
+    companion object {
+        fun parseSourceRoot(sourceRoot: String): DokkaConfiguration.SourceRoot = SourceRootImpl(sourceRoot)
+    }
+}
+
+data class PackageOptionsImpl(override val prefix: String,
+                              override val includeNonPublic: Boolean = false,
+                              override val reportUndocumented: Boolean = true,
+                              override val skipDeprecated: Boolean = false,
+                              override val suppress: Boolean = false) : DokkaConfiguration.PackageOptions
+
+class DokkaConfigurationImpl(
+    override val outputDir: String = "",
+    override val format: String = "auto-restdocs-json",
+    override val generateIndexPages: Boolean = false,
+    override val cacheRoot: String? = null,
+    override val impliedPlatforms: List<String> = emptyList(),
+    override val passesConfigurations: List<DokkaConfiguration.PassConfiguration> = listOf(PassConfigurationImpl())
+) : DokkaConfiguration
+
+class PassConfigurationImpl (
+    override val classpath: List<String> = emptyList(),
+    override val moduleName: String = "",
+    override val sourceRoots: List<DokkaConfiguration.SourceRoot> = emptyList(),
+    override val samples: List<String> = emptyList(),
+    override val includes: List<String> = emptyList(),
+    override val includeNonPublic: Boolean = false,
+    override val includeRootPackage: Boolean = false,
+    override val reportUndocumented: Boolean = false,
+    override val skipEmptyPackages: Boolean = false,
+    override val skipDeprecated: Boolean = false,
+    override val jdkVersion: Int = 8,
+    override val sourceLinks: List<DokkaConfiguration.SourceLinkDefinition> = emptyList(),
+    override val perPackageOptions: List<DokkaConfiguration.PackageOptions> = emptyList(),
+    override val externalDocumentationLinks: List<DokkaConfiguration.ExternalDocumentationLink> = emptyList(),
+    override val languageVersion: String? = null,
+    override val apiVersion: String? = null,
+    override val noStdlibLink: Boolean = false,
+    override val noJdkLink: Boolean = false,
+    override val suppressedFiles: List<String> = emptyList(),
+    override val collectInheritedExtensionsFromLibraries: Boolean = false,
+    override val analysisPlatform: Platform = Platform.DEFAULT,
+    override val targets: List<String> = emptyList(),
+    override val sinceKotlin: String? = null
+): DokkaConfiguration.PassConfiguration