Add comments and fix Javadoc generation

base/build.gradle

@@ -17,6 +17,7 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+// Plugins
 plugins {
     id("java")
     id("io.freefair.lombok") version("${pluginLombok}")
@@ -24,6 +25,7 @@ plugins {
     id("maven-publish")
 }
 
+// Project dependencies
 dependencies {
     // -> Runtime <-
     // Lombok
@@ -52,16 +54,18 @@ dependencies {
     testImplementation("org.jooq:joor:${dependencyJoor}")
 }
 
+// Git properties configuration
+// Allows us to embed git commit information in the engine build
 gitProperties {
     dotGitDirectory = file("${rootProject.rootDir}/.git")
-    failOnNoGitDirectory = false
+    failOnNoGitDirectory = false  // Allow continuing if .git directory is missing for the few who use tarballs
     extProperty = "gitProps"
 
     dateFormat = "yyyy-MM-dd'T'HH:mmZ"
     dateFormatTimeZone = "UTC"
 }
 
-tasks.register("writeGitProperties") {
+tasks.register("writeGitProperties") {  // This task's only purpose is to copy the git.properties from our git properties plugin to the resources directory so it's included in the final build
     doLast {
         File target = file("${project.projectDir}/src/main/resources/git.properties")
         File source = file("${project.projectDir}/build/resources/main/git.properties")
@@ -70,21 +74,50 @@ tasks.register("writeGitProperties") {
         source.renameTo(target)
     }
 
-    outputs.upToDateWhen({ false })
+    outputs.upToDateWhen({ false })  // Force task execution
 }
-generateGitProperties.outputs.upToDateWhen({ false })
-processResources.dependsOn(writeGitProperties)
+generateGitProperties.outputs.upToDateWhen({ false })  // Force task execution
+processResources.dependsOn(writeGitProperties)  // Ensure git.properties file is present
 
-javadoc.options {
-    setMemberLevel(JavadocMemberLevel.PUBLIC)
-    setOverview("src/main/javadoc/overview.html")
-    setLocale("en_US")
-    setJFlags([
-            // Force Javadoc to use English translations
-            "-Duser.language=en_US"
-    ])
+// Fix delombok task
+delombok.doFirst {
+    File target = file("${project.projectDir}/src/main/module-info.java")
+    File source = file("${project.projectDir}/src/main/java/module-info.java")
+
+    target.delete()
+    source.renameTo(target)
+}
+delombok.doLast {
+    File target = file("${project.projectDir}/src/main/java/module-info.java")
+    File source = file("${project.projectDir}/src/main/module-info.java")
+
+    target.delete()
+    source.renameTo(target)
 }
 
+// Javadoc configuration
+javadoc {
+    outputs.upToDateWhen { false }  // Force task execution
+    dependsOn(delombok)  // Make sure the source is delomboked first
+
+    javadoc {
+        setClasspath(files(project.sourceSets.main.compileClasspath))  // Include dependencies
+
+        options {
+            if (new File(projectDir, "src/main/javadoc/theme.css").exists())
+                stylesheetFile = new File(projectDir, "src/main/javadoc/theme.css")  // Theming is cool :3
+            setMemberLevel(JavadocMemberLevel.PUBLIC)  // Only display public stuff
+            setOverview("src/main/javadoc/overview.html")  // We want a custom overview page to greet the visitor
+            setLocale("en_US")  // 你好
+
+            setJFlags([
+                    "-Duser.language=en_US"  // See above
+            ])
+        }
+    }
+}
+
+// Unit testing configuration
 test {
     useJUnitPlatform()
     testLogging {
@@ -92,6 +125,8 @@ test {
     }
 }
 
+// Build publishing configuration
+// Note: You can safely ignore any errors or warnings thrown by your IDE here
 publishing {
     repositories {
         maven {

base/src/main/javadoc/theme.css

@@ -0,0 +1 @@
+../../../../src/main/javadoc/theme.css

build.gradle

@@ -17,19 +17,26 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+// Plugins
 plugins {
     id("java")
     id("io.freefair.lombok") version("${pluginLombok}")
     id("maven-publish")
 }
 
+// Register task for Javadoc generation for all subsystems
 tasks.register("javadocAll", Javadoc) {
+    // Task metadata
     setDescription("Generates Javadoc API documentation for all subprojects.")
     setGroup("documentation")
+    dependsOn(delombok)  // Make sure the source is delomboked first
 
     def subprojects= [
             ":base",
-            ":testapp",
+            ":graphics",
+            ":graphics:opengl",
+            ":graphics:vulkan",
+            ":slf4j-compat",
     ]
 
     setSource(subprojects.collect({ project(it).sourceSets.main.allJava }))
@@ -37,18 +44,19 @@ tasks.register("javadocAll", Javadoc) {
     setDestinationDir(file("build/docs/javadoc"))
 
     options {
-        setMemberLevel(JavadocMemberLevel.PUBLIC)
-        setOverview("src/main/javadoc/overview.html")
-        setLocale("en_US")
+        if (new File(projectDir, "src/main/javadoc/theme.css").exists())
+            stylesheetFile = new File(projectDir, "src/main/javadoc/theme.css")  // Theming is cool :3
+        setMemberLevel(JavadocMemberLevel.PUBLIC)  // Only display public stuff
+        setOverview("src/main/javadoc/overview.html")  // We want a custom overview page to greet the visitor
+        setLocale("en_US")  // 你好
+
         setJFlags([
-                // Force Javadoc to use English translations
-                "-Duser.language=en_US"
+                "-Duser.language=en_US"  // See above
         ])
     }
-
-    dependsOn(delombok)
 }
 
+// Set group, version and repositories for all projects
 allprojects {
     group = project.group
     version = project.versioningVersion + "-" + project.versioningType + project.versioningTyperelease + project.versioningFork

graphics/build.gradle

@@ -17,11 +17,13 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+// Plugins
 plugins {
     id("java")
     id("io.freefair.lombok") version("${pluginLombok}")
 }
 
+// Dependencies
 dependencies {
     // -> Runtime <-
     // Lombok
@@ -48,16 +50,45 @@ dependencies {
     implementation("org.fusesource.jansi:jansi:${dependencyJansi}")  // for some reason required or the build fails don"t ask me why
 }
 
-javadoc.options {
-    setMemberLevel(JavadocMemberLevel.PUBLIC)
-    setOverview("src/main/javadoc/overview.html")
-    setLocale("en_US")
-    setJFlags([
-            // Force Javadoc to use English translations
-            "-Duser.language=en_US"
-    ])
+// Fix delombok task
+delombok.doFirst {
+    File target = file("${project.projectDir}/src/main/module-info.java")
+    File source = file("${project.projectDir}/src/main/java/module-info.java")
+
+    target.delete()
+    source.renameTo(target)
+}
+delombok.doLast {
+    File target = file("${project.projectDir}/src/main/java/module-info.java")
+    File source = file("${project.projectDir}/src/main/module-info.java")
+
+    target.delete()
+    source.renameTo(target)
 }
 
+// Javadoc configuration
+javadoc {
+    outputs.upToDateWhen { false }  // Force task execution
+    dependsOn(delombok)  // Make sure the source is delomboked first
+
+    javadoc {
+        setClasspath(files(project.sourceSets.main.compileClasspath))  // Include dependencies
+
+        options {
+            if (new File(projectDir, "src/main/javadoc/theme.css").exists())
+                stylesheetFile = new File(projectDir, "src/main/javadoc/theme.css")  // Theming is cool :3
+            setMemberLevel(JavadocMemberLevel.PUBLIC)  // Only display public stuff
+            setOverview("src/main/javadoc/overview.html")  // We want a custom overview page to greet the visitor
+            setLocale("en_US")  // 你好
+
+            setJFlags([
+                    "-Duser.language=en_US"  // See above
+            ])
+        }
+    }
+}
+
+// Unit testing configuration
 test {
     useJUnitPlatform()
     testLogging {

graphics/opengl/build.gradle

@@ -19,12 +19,13 @@
 
 import org.gradle.internal.os.OperatingSystem
 
+// Plugins
 plugins {
     id("java")
     id("io.freefair.lombok") version("${pluginLombok}")
 }
 
-// Determine LWJGL native stuff
+// Determine operating system and architecture
 switch (OperatingSystem.current()) {
     case OperatingSystem.LINUX:
         project.dependencyLwjglNatives = "natives-linux"
@@ -48,6 +49,7 @@ switch (OperatingSystem.current()) {
         break
 }
 
+// Dependencies
 dependencies {
     // -> Runtime <-
     // Lombok
@@ -98,16 +100,45 @@ dependencies {
     implementation("org.fusesource.jansi:jansi:${dependencyJansi}")  // for some reason required or the build fails don"t ask me why
 }
 
-javadoc.options {
-    setMemberLevel(JavadocMemberLevel.PUBLIC)
-    setOverview("src/main/javadoc/overview.html")
-    setLocale("en_US")
-    setJFlags([
-            // Force Javadoc to use English translations
-            "-Duser.language=en_US"
-    ])
+// Fix delombok task
+delombok.doFirst {
+    File target = file("${project.projectDir}/src/main/module-info.java")
+    File source = file("${project.projectDir}/src/main/java/module-info.java")
+
+    target.delete()
+    source.renameTo(target)
+}
+delombok.doLast {
+    File target = file("${project.projectDir}/src/main/java/module-info.java")
+    File source = file("${project.projectDir}/src/main/module-info.java")
+
+    target.delete()
+    source.renameTo(target)
 }
 
+// Javadoc configuration
+javadoc {
+    outputs.upToDateWhen { false }  // Force task execution
+    dependsOn(delombok)  // Make sure the source is delomboked first
+
+    javadoc {
+        setClasspath(files(project.sourceSets.main.compileClasspath))  // Include dependencies
+
+        options {
+            if (new File(projectDir, "src/main/javadoc/theme.css").exists())
+                stylesheetFile = new File(projectDir, "src/main/javadoc/theme.css")  // Theming is cool :3
+            setMemberLevel(JavadocMemberLevel.PUBLIC)  // Only display public stuff
+            setOverview("src/main/javadoc/overview.html")  // We want a custom overview page to greet the visitor
+            setLocale("en_US")  // 你好
+
+            setJFlags([
+                    "-Duser.language=en_US"  // See above
+            ])
+        }
+    }
+}
+
+// Unit testing configuration
 test {
     useJUnitPlatform()
     testLogging {

graphics/opengl/src/main/javadoc/theme.css

@@ -0,0 +1 @@
+../../../../../src/main/javadoc/theme.css

graphics/src/main/javadoc/theme.css

@@ -0,0 +1 @@
+../../../../src/main/javadoc/theme.css

graphics/vulkan/build.gradle

@@ -19,12 +19,13 @@
 
 import org.gradle.internal.os.OperatingSystem
 
+// Plugins
 plugins {
     id("java")
     id("io.freefair.lombok") version("${pluginLombok}")
 }
 
-// Determine LWJGL native stuff
+// Determine operating system and architecture
 switch (OperatingSystem.current()) {
     case OperatingSystem.LINUX:
         project.dependencyLwjglNatives = "natives-linux"
@@ -48,6 +49,7 @@ switch (OperatingSystem.current()) {
         break
 }
 
+// Dependencies
 dependencies {
     // -> Runtime <-
     // Lombok
@@ -95,16 +97,45 @@ dependencies {
     implementation("org.fusesource.jansi:jansi:${dependencyJansi}")  // for some reason required or the build fails don"t ask me why
 }
 
-javadoc.options {
-    setMemberLevel(JavadocMemberLevel.PUBLIC)
-    setOverview("src/main/javadoc/overview.html")
-    setLocale("en_US")
-    setJFlags([
-            // Force Javadoc to use English translations
-            "-Duser.language=en_US"
-    ])
+// Fix delombok task
+delombok.doFirst {
+    File target = file("${project.projectDir}/src/main/module-info.java")
+    File source = file("${project.projectDir}/src/main/java/module-info.java")
+
+    target.delete()
+    source.renameTo(target)
+}
+delombok.doLast {
+    File target = file("${project.projectDir}/src/main/java/module-info.java")
+    File source = file("${project.projectDir}/src/main/module-info.java")
+
+    target.delete()
+    source.renameTo(target)
 }
 
+// Javadoc configuration
+javadoc {
+    outputs.upToDateWhen { false }  // Force task execution
+    dependsOn(delombok)  // Make sure the source is delomboked first
+
+    javadoc {
+        setClasspath(files(project.sourceSets.main.compileClasspath))  // Include dependencies
+
+        options {
+            if (new File(projectDir, "src/main/javadoc/theme.css").exists())
+                stylesheetFile = new File(projectDir, "src/main/javadoc/theme.css")  // Theming is cool :3
+            setMemberLevel(JavadocMemberLevel.PUBLIC)  // Only display public stuff
+            setOverview("src/main/javadoc/overview.html")  // We want a custom overview page to greet the visitor
+            setLocale("en_US")  // 你好
+
+            setJFlags([
+                    "-Duser.language=en_US"  // See above
+            ])
+        }
+    }
+}
+
+// Unit testing configuration
 test {
     useJUnitPlatform()
     testLogging {

graphics/vulkan/src/main/javadoc/theme.css

@@ -0,0 +1 @@
+../../../../../src/main/javadoc/theme.css

slf4j-compat/build.gradle

@@ -17,12 +17,14 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+// Plugins
 plugins {
     id("java")
     id("io.freefair.lombok") version("${pluginLombok}")
     id("maven-publish")
 }
 
+// Dependencies
 dependencies {
     // -> Runtime <-
     // Lombok
@@ -40,23 +42,46 @@ dependencies {
     implementation("org.fusesource.jansi:jansi:${dependencyJansi}")  // for some reason required or the build fails don"t ask me why
 }
 
-javadoc.options {
-    setMemberLevel(JavadocMemberLevel.PUBLIC)
-    setOverview("src/main/javadoc/overview.html")
-    setLocale("en_US")
-    setJFlags([
-            // Force Javadoc to use English translations
-            "-Duser.language=en_US"
-    ])
+// Fix delombok task
+delombok.doFirst {
+    File target = file("${project.projectDir}/src/main/module-info.java")
+    File source = file("${project.projectDir}/src/main/java/module-info.java")
+
+    target.delete()
+    source.renameTo(target)
+}
+delombok.doLast {
+    File target = file("${project.projectDir}/src/main/java/module-info.java")
+    File source = file("${project.projectDir}/src/main/module-info.java")
+
+    target.delete()
+    source.renameTo(target)
 }
 
-test {
-    useJUnitPlatform()
-    testLogging {
-        events("passed", "skipped", "failed")
+// Javadoc configuration
+javadoc {
+    outputs.upToDateWhen { false }  // Force task execution
+    dependsOn(delombok)  // Make sure the source is delomboked first
+
+    javadoc {
+        setClasspath(files(project.sourceSets.main.compileClasspath))  // Include dependencies
+
+        options {
+            if (new File(projectDir, "src/main/javadoc/theme.css").exists())
+                stylesheetFile = new File(projectDir, "src/main/javadoc/theme.css")  // Theming is cool :3
+            setMemberLevel(JavadocMemberLevel.PUBLIC)  // Only display public stuff
+            setOverview("src/main/javadoc/overview.html")  // We want a custom overview page to greet the visitor
+            setLocale("en_US")  // 你好
+
+            setJFlags([
+                    "-Duser.language=en_US"  // See above
+            ])
+        }
     }
 }
 
+// Build publishing configuration
+// Note: You can safely ignore any errors or warnings thrown by your IDE here
 publishing {
     repositories {
         maven {

slf4j-compat/src/main/javadoc/theme.css

@@ -0,0 +1 @@
+../../../../src/main/javadoc/theme.css

src/main/javadoc/theme.css

@@ -0,0 +1 @@
+

testapp/build.gradle

@@ -17,6 +17,7 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+// Plugins
 plugins {
     id("java")
     id "application"
@@ -25,6 +26,7 @@ plugins {
     id('org.mikeneck.graalvm-native-image') version("${pluginNativeImage}")
 }
 
+// Dependencies
 dependencies {
     // -> Runtime <-
     // Lombok
@@ -43,16 +45,23 @@ dependencies {
     implementation("org.fusesource.jansi:jansi:${dependencyJansi}")  // for some reason required or the build fails don"t ask me why
 }
 
-javadoc.options {
-    setMemberLevel(JavadocMemberLevel.PUBLIC)
-    setOverview("src/main/javadoc/overview.html")
-    setLocale("en_US")
-    setJFlags([
-            // Force Javadoc to use English translations
-            "-Duser.language=en_US"
-    ])
+// Fix delombok task
+delombok.doFirst {
+    File target = file("${project.projectDir}/src/main/module-info.java")
+    File source = file("${project.projectDir}/src/main/java/module-info.java")
+
+    target.delete()
+    source.renameTo(target)
+}
+delombok.doLast {
+    File target = file("${project.projectDir}/src/main/java/module-info.java")
+    File source = file("${project.projectDir}/src/main/module-info.java")
+
+    target.delete()
+    source.renameTo(target)
 }
 
+// Configure output jar
 jar {
     manifest {
         attributes(
@@ -61,9 +70,10 @@ jar {
     }
 }
 
+// Configure application run task
 application {
     mainClass.set("de.staropensource.sosengine.testapp.Main")
-    applicationDefaultJvmArgs = [
+    applicationDefaultJvmArgs = [  // List of nice development configuration overrides
             // Set log level to DIAGNOSTIC
             "-Dsosengine.base.loggerLevel=diagnostic",
 
@@ -75,6 +85,7 @@ application {
     ]
 }
 
+// GraalVM native-image plugin configuration
 nativeImage {
     graalVmHome = project.hasProperty("graalHome") ? project.property("graalHome") as String : System.getProperty("java.home")
     mainClass = "de.staropensource.sosengine.testapp.Main"
@@ -87,6 +98,7 @@ nativeImage {
     }
 }
 
+// Register task for executing the generated binary
 tasks.register('runNativeimage', Exec) {
     dependsOn(nativeImage)
     executable("build/bin/sosengine-testapp")