CORDA-692 Don't include internal packages in API documentation (#2415)

* Use G1 for gradle daemon

build.gradle

@@ -56,7 +56,7 @@ buildscript {
     ext.h2_version = '1.4.194' // Update docs if renamed or removed.
     ext.postgresql_version = '42.1.4'
     ext.rxjava_version = '1.2.4'
-    ext.dokka_version = '0.9.14'
+    ext.dokka_version = '0.9.16-eap-2'
     ext.eddsa_version = '0.2.0'
     ext.dependency_checker_version = '3.0.1'
     ext.commons_collections_version = '4.1'
@@ -73,6 +73,9 @@ buildscript {
         mavenLocal()
         mavenCentral()
         jcenter()
+        maven {
+            url 'https://dl.bintray.com/kotlin/kotlin-eap/'
+        }
     }
     dependencies {
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"

core/src/main/kotlin/net/corda/core/internal/InternalUtils.kt

@@ -254,13 +254,12 @@ fun <T> Class<*>.staticField(name: String): DeclaredField<T> = DeclaredField(thi
 /** Returns a [DeclaredField] wrapper around the declared (possibly non-public) static field of the receiver [KClass]. */
 fun <T> KClass<*>.staticField(name: String): DeclaredField<T> = DeclaredField(java, name, null)
 
-/** @suppress Returns a [DeclaredField] wrapper around the declared (possibly non-public) instance field of the receiver object. */
+/** Returns a [DeclaredField] wrapper around the declared (possibly non-public) instance field of the receiver object. */
 fun <T> Any.declaredField(name: String): DeclaredField<T> = DeclaredField(javaClass, name, this)
 
 /**
  * Returns a [DeclaredField] wrapper around the (possibly non-public) instance field of the receiver object, but declared
  * in its superclass [clazz].
- * @suppress
  */
 fun <T> Any.declaredField(clazz: KClass<*>, name: String): DeclaredField<T> = DeclaredField(clazz.java, name, this)
 
@@ -295,18 +294,12 @@ fun <T, U : T> uncheckedCast(obj: T) = obj as U
 
 fun <K, V> Iterable<Pair<K, V>>.toMultiMap(): Map<K, List<V>> = this.groupBy({ it.first }) { it.second }
 
-/**
+/** Provide access to internal method for AttachmentClassLoaderTests */
- * Provide access to internal method for AttachmentClassLoaderTests
- * @suppress
- */
 fun TransactionBuilder.toWireTransaction(cordappProvider: CordappProvider, serializationContext: SerializationContext): WireTransaction {
     return toWireTransactionWithContext(cordappProvider, serializationContext)
 }
 
-/**
+/** Provide access to internal method for AttachmentClassLoaderTests */
- * Provide access to internal method for AttachmentClassLoaderTests
- * @suppress
- */
 fun TransactionBuilder.toLedgerTransaction(services: ServicesForResolution, serializationContext: SerializationContext) = toLedgerTransactionWithContext(services, serializationContext)
 
 /** Convenience method to get the package name of a class literal. */

docs/build.gradle

@@ -5,40 +5,42 @@ dependencies {
     compile rootProject
 }
 
+def internalPackagePrefixes(sourceDirs) {
+    def prefixes = []
+    // Kotlin allows packages to deviate from the directory structure, but let's assume they don't:
+    sourceDirs.collect { sourceDir ->
+        sourceDir.traverse(type: groovy.io.FileType.DIRECTORIES) {
+            if (it.name == 'internal') {
+                prefixes.add sourceDir.toPath().relativize(it.toPath()).toString().replace(File.separator, '.')
+            }
+        }
+    }
+    prefixes
+}
+
 ext {
     // TODO: Add '../client/jfx/src/main/kotlin' and '../client/mock/src/main/kotlin' if we decide to make them into public API
     dokkaSourceDirs = files('../core/src/main/kotlin', '../client/rpc/src/main/kotlin', '../finance/src/main/kotlin', '../client/jackson/src/main/kotlin',
                             '../testing/test-utils/src/main/kotlin', '../testing/node-driver/src/main/kotlin')
+    internalPackagePrefixes = internalPackagePrefixes(dokkaSourceDirs)
 }
 
 dokka {
-    moduleName = 'corda'
     outputDirectory = file("${rootProject.rootDir}/docs/build/html/api/kotlin")
-    processConfigurations = ['compile']
-    sourceDirs = dokkaSourceDirs
-    includes = ['packages.md']
-    jdkVersion = 8
-
-    externalDocumentationLink {
-        url = new URL("http://fasterxml.github.io/jackson-core/javadoc/2.8/")
-    }
-    externalDocumentationLink {
-        url = new URL("https://docs.oracle.com/javafx/2/api/")
-    }
-    externalDocumentationLink {
-        url = new URL("http://www.bouncycastle.org/docs/docs1.5on/")
-    }
 }
 
 task dokkaJavadoc(type: org.jetbrains.dokka.gradle.DokkaTask) {
-    moduleName = 'corda'
     outputFormat = "javadoc"
     outputDirectory = file("${rootProject.rootDir}/docs/build/html/api/javadoc")
+}
+
+[dokka, dokkaJavadoc].collect {
+    it.configure {
+        moduleName = 'corda'
         processConfigurations = ['compile']
         sourceDirs = dokkaSourceDirs
         includes = ['packages.md']
         jdkVersion = 8
-
         externalDocumentationLink {
             url = new URL("http://fasterxml.github.io/jackson-core/javadoc/2.8/")
         }
@@ -48,6 +50,13 @@ task dokkaJavadoc(type: org.jetbrains.dokka.gradle.DokkaTask) {
         externalDocumentationLink {
             url = new URL("http://www.bouncycastle.org/docs/docs1.5on/")
         }
+        internalPackagePrefixes.collect { packagePrefix ->
+            packageOptions {
+                prefix = packagePrefix
+                suppress = true
+            }
+        }
+    }
 }
 
 task buildDocs(dependsOn: ['apidocs', 'makeDocs'])

docs/packages.md

@@ -23,7 +23,7 @@ is complete.
 # Package net.corda.core.contracts
 
 This package contains the base data types for smarts contracts implemented in Corda. To implement a new contract start
-with [Contract], or see the examples in [net.corda.finance.contracts].
+with [Contract], or see the examples in `net.corda.finance.contracts`.
 
 Corda smart contracts are a combination of state held on the distributed ledger, and verification logic which defines
 which transformations of state are valid.

gradle.properties

@@ -1 +1,2 @@
 kotlin.incremental=true
+org.gradle.jvmargs=-XX:+UseG1GC -Xmx1g

node/src/main/kotlin/net/corda/node/internal/AbstractNode.kt

@@ -508,7 +508,6 @@ abstract class AbstractNode(val configuration: NodeConfiguration,
      * Installs a flow that's core to the Corda platform. Unlike CorDapp flows which are versioned individually using
      * [InitiatingFlow.version], core flows have the same version as the node's platform version. To cater for backwards
      * compatibility [flowFactory] provides a second parameter which is the platform version of the initiating party.
-     * @suppress
      */
     @VisibleForTesting
     fun installCoreFlow(clientFlowClass: KClass<out FlowLogic<*>>, flowFactory: (FlowSession) -> FlowLogic<*>) {