From 242d9cf7ade854d75ec4781edfaf16034b3b6217 Mon Sep 17 00:00:00 2001 From: Andrzej Cichocki Date: Thu, 25 Jan 2018 15:26:13 +0000 Subject: [PATCH] CORDA-692 Don't include internal packages in API documentation (#2415) * Use G1 for gradle daemon --- build.gradle | 5 +- .../net/corda/core/internal/InternalUtils.kt | 13 +--- docs/build.gradle | 65 +++++++++++-------- docs/packages.md | 2 +- gradle.properties | 1 + .../net/corda/node/internal/AbstractNode.kt | 1 - 6 files changed, 46 insertions(+), 41 deletions(-) diff --git a/build.gradle b/build.gradle index a64dc578eb..66e94fd571 100644 --- a/build.gradle +++ b/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" diff --git a/core/src/main/kotlin/net/corda/core/internal/InternalUtils.kt b/core/src/main/kotlin/net/corda/core/internal/InternalUtils.kt index 70724cb884..6d22445cb6 100644 --- a/core/src/main/kotlin/net/corda/core/internal/InternalUtils.kt +++ b/core/src/main/kotlin/net/corda/core/internal/InternalUtils.kt @@ -254,13 +254,12 @@ fun Class<*>.staticField(name: String): DeclaredField = DeclaredField(thi /** Returns a [DeclaredField] wrapper around the declared (possibly non-public) static field of the receiver [KClass]. */ fun KClass<*>.staticField(name: String): DeclaredField = 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 Any.declaredField(name: String): DeclaredField = 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 Any.declaredField(clazz: KClass<*>, name: String): DeclaredField = DeclaredField(clazz.java, name, this) @@ -295,18 +294,12 @@ fun uncheckedCast(obj: T) = obj as U fun Iterable>.toMultiMap(): Map> = this.groupBy({ it.first }) { it.second } -/** - * Provide access to internal method for AttachmentClassLoaderTests - * @suppress - */ +/** Provide access to internal method for AttachmentClassLoaderTests */ fun TransactionBuilder.toWireTransaction(cordappProvider: CordappProvider, serializationContext: SerializationContext): WireTransaction { return toWireTransactionWithContext(cordappProvider, serializationContext) } -/** - * Provide access to internal method for AttachmentClassLoaderTests - * @suppress - */ +/** Provide access to internal method for AttachmentClassLoaderTests */ fun TransactionBuilder.toLedgerTransaction(services: ServicesForResolution, serializationContext: SerializationContext) = toLedgerTransactionWithContext(services, serializationContext) /** Convenience method to get the package name of a class literal. */ diff --git a/docs/build.gradle b/docs/build.gradle index a0d60a371e..0da6f2ecca 100644 --- a/docs/build.gradle +++ b/docs/build.gradle @@ -5,48 +5,57 @@ 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") - 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/") +[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/") + } + externalDocumentationLink { + url = new URL("https://docs.oracle.com/javafx/2/api/") + } + externalDocumentationLink { + url = new URL("http://www.bouncycastle.org/docs/docs1.5on/") + } + internalPackagePrefixes.collect { packagePrefix -> + packageOptions { + prefix = packagePrefix + suppress = true + } + } } } diff --git a/docs/packages.md b/docs/packages.md index 7331383ccc..2be38afd1e 100644 --- a/docs/packages.md +++ b/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. diff --git a/gradle.properties b/gradle.properties index 152a881d36..59e65ce554 100644 --- a/gradle.properties +++ b/gradle.properties @@ -1 +1,2 @@ kotlin.incremental=true +org.gradle.jvmargs=-XX:+UseG1GC -Xmx1g diff --git a/node/src/main/kotlin/net/corda/node/internal/AbstractNode.kt b/node/src/main/kotlin/net/corda/node/internal/AbstractNode.kt index 8b3e992ef1..42355c78f4 100644 --- a/node/src/main/kotlin/net/corda/node/internal/AbstractNode.kt +++ b/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>, flowFactory: (FlowSession) -> FlowLogic<*>) {