Merge branch '28-web-javadoc-task' into dev

Author: greenrobot-team

Jenkinsfile

@@ -42,6 +42,7 @@ pipeline {
         stage('init') {
             steps {
                 sh 'chmod +x gradlew'
+                sh './gradlew -version'
 
                 // "|| true" for an OK exit code if no file is found
                 sh 'rm tests/objectbox-java-test/hs_err_pid*.log || true'

ci/Jenkinsfile-Windows

@@ -25,6 +25,8 @@ pipeline {
     stages {
         stage('init') {
             steps {
+                bat 'gradlew -version'
+
                 // "cmd /c" for an OK exit code if no file is found
                 bat 'cmd /c del tests\\objectbox-java-test\\hs_err_pid*.log'
             }

objectbox-java-api/build.gradle

@@ -5,12 +5,6 @@ version= rootProject.version
 
 sourceCompatibility = 1.7
 
-javadoc {
-    failOnError = false
-    title = "ObjectBox API ${version} API"
-    options.bottom = 'Available under the Apache License, Version 2.0 - <i>Copyright &#169; 2017-2020 <a href="http://objectbox.io/">ObjectBox Ltd</a>. All Rights Reserved.</i>'
-}
-
 task javadocJar(type: Jar, dependsOn: javadoc) {
     classifier = 'javadoc'
     from 'build/docs/javadoc'

objectbox-java/build.gradle

@@ -23,10 +23,7 @@ dependencies {
 }
 
 javadoc {
-    failOnError = false
-    title = "ObjectBox Java ${version} API"
-    options.bottom = 'Available under the Apache License, Version 2.0 - <i>Copyright &#169; 2017-2020 <a href="http://objectbox.io/">ObjectBox Ltd</a>. All Rights Reserved.</i>'
-    exclude("**/com/google/**")
+    // Hide internal API from javadoc artifact.
     exclude("**/io/objectbox/Cursor.java")
     exclude("**/io/objectbox/KeyValueCursor.java")
     exclude("**/io/objectbox/ModelBuilder.java")
@@ -37,12 +34,40 @@ javadoc {
     exclude("**/io/objectbox/internal/**")
     exclude("**/io/objectbox/reactive/DataPublisherUtils.java")
     exclude("**/io/objectbox/reactive/WeakDataObserver.java")
+}
+
+// Note: use packageJavadocForWeb to get as ZIP.
+// Note: the style changes only work if using JDK 10+.
+task javadocForWeb(type: Javadoc) {
+    group = 'documentation'
+    description = 'Builds Javadoc incl. objectbox-java-api classes with web tweaks.'
+
     def srcApi = project(':objectbox-java-api').file('src/main/java/')
     if (!srcApi.directory) throw new GradleScriptException("Not a directory: ${srcApi}", null)
-    source += srcApi
+    // Hide internal API from javadoc artifact.
+    def filteredSources = sourceSets.main.allJava.matching {
+        exclude("**/io/objectbox/Cursor.java")
+        exclude("**/io/objectbox/KeyValueCursor.java")
+        exclude("**/io/objectbox/ModelBuilder.java")
+        exclude("**/io/objectbox/Properties.java")
+        exclude("**/io/objectbox/Transaction.java")
+        exclude("**/io/objectbox/model/**")
+        exclude("**/io/objectbox/ideasonly/**")
+        exclude("**/io/objectbox/internal/**")
+        exclude("**/io/objectbox/reactive/DataPublisherUtils.java")
+        exclude("**/io/objectbox/reactive/WeakDataObserver.java")
+    }
+    source = filteredSources + srcApi
+
+    classpath = sourceSets.main.output + sourceSets.main.compileClasspath
+    destinationDir = reporting.file("web-api-docs")
+
+    title = "ObjectBox Java ${version} API"
+    options.bottom = 'Available under the Apache License, Version 2.0 - <i>Copyright &#169; 2017-2020 <a href="http://objectbox.io/">ObjectBox Ltd</a>. All Rights Reserved.</i>'
+
     doLast {
         // Note: frequently check the vanilla stylesheet.css if values still match.
-        def stylesheetPath = "$buildDir/docs/javadoc/stylesheet.css"
+        def stylesheetPath = "$destinationDir/stylesheet.css"
 
         // Primary background
         ant.replace(file: stylesheetPath, token: "#4D7A97", value: "#17A6A6")
@@ -68,6 +93,20 @@ javadoc {
     }
 }
 
+task packageJavadocForWeb(type: Zip, dependsOn: javadocForWeb) {
+    group = 'documentation'
+    description = 'Packages Javadoc incl. objectbox-java-api classes with web tweaks as ZIP.'
+
+    archiveFileName = "objectbox-java-web-api-docs.zip"
+    destinationDirectory = file("$buildDir/dist")
+
+    from reporting.file("web-api-docs")
+
+    doLast {
+        println "Javadoc for web packaged to ${file("$buildDir/dist/objectbox-java-web-api-docs.zip")}"
+    }
+}
+
 task javadocJar(type: Jar, dependsOn: javadoc) {
     classifier = 'javadoc'
     from 'build/docs/javadoc'

objectbox-java/src/main/java/io/objectbox/model/PropertyFlags.java

@@ -73,11 +73,11 @@ private PropertyFlags() { }
   public static final int INDEX_HASH = 2048;
   /**
    * Index uses a 64 bit hash instead of the value
-   * (recommended mostly for 64 bit machines with values longer >200 bytes; small values are faster with a 32 bit hash)
+   * (recommended mostly for 64 bit machines with values longer than 200 bytes; small values are faster with a 32 bit hash)
    */
   public static final int INDEX_HASH64 = 4096;
   /**
-   * Unused yet: While our default are signed ints, queries & indexes need do know signing info.
+   * Unused yet: While our default are signed ints, queries and indexes need do know signing info.
    * Note: Don't combine with ID (IDs are always unsigned internally).
    */
   public static final int UNSIGNED = 8192;

objectbox-kotlin/build.gradle

@@ -4,7 +4,7 @@ version= rootProject.version
 buildscript {
     ext.javadocDir = "$buildDir/docs/javadoc"
     ext.kotlin_version = '1.3.31'
-    ext.dokka_version = '0.9.18'
+    ext.dokka_version = '0.10.0'
 
     repositories {
         mavenCentral()
@@ -25,6 +25,17 @@ sourceCompatibility = 1.7
 dokka {
     outputFormat = 'html'
     outputDirectory = javadocDir
+
+    // Fix "Can't find node by signature": have to manually point to dependencies.
+    // https://github.com/Kotlin/dokka/wiki/faq#dokka-complains-about-cant-find-node-by-signature-
+    configuration{
+        externalDocumentationLink {
+            // Point to web javadoc for objectbox-java packages.
+            url = new URL("https://objectbox.io/docfiles/java/current/")
+            // Note: Using JDK 9+ package-list is now called element-list.
+            packageListUrl = new URL(url, "element-list")
+        }
+    }
 }
 
 task javadocJar(type: Jar, dependsOn: dokka) {

objectbox-kotlin/src/main/kotlin/io/objectbox/kotlin/Extensions.kt

@@ -26,8 +26,10 @@ import io.objectbox.query.QueryBuilder
 import io.objectbox.relation.ToMany
 import kotlin.reflect.KClass
 
+/** Shortcut for `BoxStore.boxFor(Entity::class.java)`. */
 inline fun <reified T> BoxStore.boxFor(): Box<T> = boxFor(T::class.java)
 
+/** Shortcut for `BoxStore.boxFor(Entity::class.java)`. */
 @Suppress("NOTHING_TO_INLINE")
 inline fun <T : Any> BoxStore.boxFor(clazz: KClass<T>): Box<T> = boxFor(clazz.java)
 

objectbox-rxjava/build.gradle

@@ -13,13 +13,6 @@ dependencies {
     testCompile 'org.mockito:mockito-core:2.25.1'
 }
 
-javadoc {
-    failOnError = false
-    title = "ObjectBox RxJava2 ${version} API"
-    excludes = [] // Unfinished APIs if any
-    options.bottom = 'Available under the Apache License, Version 2.0 - <i>Copyright &#169; 2018-2020 <a href="http://objectbox.io/">ObjectBox Ltd</a>. All Rights Reserved.</i>'
-}
-
 task javadocJar(type: Jar, dependsOn: javadoc) {
     classifier = 'javadoc'
     from 'build/docs/javadoc'