From fa3d2ec19d96c6e7e9c61c32c1908ce98b8777f8 Mon Sep 17 00:00:00 2001 From: JeremyStarTM Date: Thu, 11 Jul 2024 04:03:08 +0200 Subject: [PATCH] Add comments and fix Javadoc generation --- base/build.gradle | 61 +++++++++++++++++----- base/src/main/javadoc/theme.css | 1 + build.gradle | 24 ++++++--- graphics/build.gradle | 47 ++++++++++++++--- graphics/opengl/build.gradle | 49 +++++++++++++---- graphics/opengl/src/main/javadoc/theme.css | 1 + graphics/src/main/javadoc/theme.css | 1 + graphics/vulkan/build.gradle | 49 +++++++++++++---- graphics/vulkan/src/main/javadoc/theme.css | 1 + slf4j-compat/build.gradle | 49 ++++++++++++----- slf4j-compat/src/main/javadoc/theme.css | 1 + src/main/javadoc/theme.css | 1 + testapp/build.gradle | 30 +++++++---- 13 files changed, 247 insertions(+), 68 deletions(-) create mode 120000 base/src/main/javadoc/theme.css create mode 120000 graphics/opengl/src/main/javadoc/theme.css create mode 120000 graphics/src/main/javadoc/theme.css create mode 120000 graphics/vulkan/src/main/javadoc/theme.css create mode 120000 slf4j-compat/src/main/javadoc/theme.css create mode 100644 src/main/javadoc/theme.css diff --git a/base/build.gradle b/base/build.gradle index be5c528..8e5b9a0 100644 --- a/base/build.gradle +++ b/base/build.gradle @@ -17,6 +17,7 @@ * along with this program. If not, see . */ +// 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 { diff --git a/base/src/main/javadoc/theme.css b/base/src/main/javadoc/theme.css new file mode 120000 index 0000000..681484a --- /dev/null +++ b/base/src/main/javadoc/theme.css @@ -0,0 +1 @@ +../../../../src/main/javadoc/theme.css \ No newline at end of file diff --git a/build.gradle b/build.gradle index 33e9eee..b8c0baf 100644 --- a/build.gradle +++ b/build.gradle @@ -17,19 +17,26 @@ * along with this program. If not, see . */ +// 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 diff --git a/graphics/build.gradle b/graphics/build.gradle index 8a12ad2..9dbee34 100644 --- a/graphics/build.gradle +++ b/graphics/build.gradle @@ -17,11 +17,13 @@ * along with this program. If not, see . */ +// 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 { diff --git a/graphics/opengl/build.gradle b/graphics/opengl/build.gradle index 29422fa..645466b 100644 --- a/graphics/opengl/build.gradle +++ b/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 { diff --git a/graphics/opengl/src/main/javadoc/theme.css b/graphics/opengl/src/main/javadoc/theme.css new file mode 120000 index 0000000..bccac6b --- /dev/null +++ b/graphics/opengl/src/main/javadoc/theme.css @@ -0,0 +1 @@ +../../../../../src/main/javadoc/theme.css \ No newline at end of file diff --git a/graphics/src/main/javadoc/theme.css b/graphics/src/main/javadoc/theme.css new file mode 120000 index 0000000..681484a --- /dev/null +++ b/graphics/src/main/javadoc/theme.css @@ -0,0 +1 @@ +../../../../src/main/javadoc/theme.css \ No newline at end of file diff --git a/graphics/vulkan/build.gradle b/graphics/vulkan/build.gradle index d3b878f..de0bd12 100644 --- a/graphics/vulkan/build.gradle +++ b/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 { diff --git a/graphics/vulkan/src/main/javadoc/theme.css b/graphics/vulkan/src/main/javadoc/theme.css new file mode 120000 index 0000000..bccac6b --- /dev/null +++ b/graphics/vulkan/src/main/javadoc/theme.css @@ -0,0 +1 @@ +../../../../../src/main/javadoc/theme.css \ No newline at end of file diff --git a/slf4j-compat/build.gradle b/slf4j-compat/build.gradle index c4bc3e3..fae709f 100644 --- a/slf4j-compat/build.gradle +++ b/slf4j-compat/build.gradle @@ -17,12 +17,14 @@ * along with this program. If not, see . */ +// 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 { diff --git a/slf4j-compat/src/main/javadoc/theme.css b/slf4j-compat/src/main/javadoc/theme.css new file mode 120000 index 0000000..681484a --- /dev/null +++ b/slf4j-compat/src/main/javadoc/theme.css @@ -0,0 +1 @@ +../../../../src/main/javadoc/theme.css \ No newline at end of file diff --git a/src/main/javadoc/theme.css b/src/main/javadoc/theme.css new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/src/main/javadoc/theme.css @@ -0,0 +1 @@ + diff --git a/testapp/build.gradle b/testapp/build.gradle index e316e00..1f6aa6d 100644 --- a/testapp/build.gradle +++ b/testapp/build.gradle @@ -17,6 +17,7 @@ * along with this program. If not, see . */ +// 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")