Start documenting some of the bradle scripts.

Signed-off-by: Gabriel Harris-Rouquette <gabizou@me.com>

README.md

@@ -8,6 +8,22 @@ You can check it out here http://www.mcmmo.org
 
 I plan to post links to our new wiki (its still under development), downloads, and dev blogs there.
 
+### Contributing
+As the plugin is being developed for multiple Minecraft versions, and multiple Minecraft platforms (read: [sponge](https://spongepowered.org/), [spigot](https://spigotmc.org/), bukkit, and [paper](https://papermc.io)), the
+overall build process is handled by [Gradle](https://gradle.org/) with [Kotlin-dsl](https://github.com/gradle/kotlin-dsl) based scripts.
+As such, an IDE is strongly recommended when attempting to contribute features, additions, changes, bug fixes, etc. to mcMMO as the scripts handle a
+majority of our dependencies and rebuilding a production worthy jar.
+
+To get started, a few things need to be installed:
+- JDK 8 (not 9, 10, 11, or 7)
+- git
+- Your favorite IDE (can be [Eclipse](https://eclipse.org/), [IntelliJ](https://jetbrains.org/)
+- BuildTools.jar from [Spigot](https://www.spigotmc.org/wiki/buildtools/)
+
+##### Using BuildTools
+BuildTools is used to generate the craftbukkit/spigot dependencies used for varoius versions of Minecraft.
+The key with this tool is that it can build and deploy multiple vesions of Minecraft based on "reviewions".
+
 
 ### Builds
 Currently, you can obtain our builds via the Spigot resource page: https://spigot.mcmmo.org

build.gradle.kts

@@ -1,24 +1,29 @@
 import com.github.jengelman.gradle.plugins.shadow.tasks.ConfigureShadowRelocation
 import com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar
 
-buildscript {
-    repositories {
-        jcenter()
-        maven("https://files.minecraftforge.net/maven/")
-    }
-    dependencies {
-        classpath("net.minecraftforge.gradle:ForgeGradle:2.3-SNAPSHOT")
-    }
-}
-
+/*
+ * Declares the version of the Gradle wrapper. We need 4.9 for now because
+ * ForgeGradle 3+ is a hard dependency for Gradle 4.9, 4.10 is not compatible
+ */
 val wrapper by tasks.getting(Wrapper::class) {
   gradleVersion = "4.9"
 }
 
-// Things used by other projects
+/*
+ * Sets up project references to be used in child scripts, like
+ * ":bukkit", ":core", ":sponge" where these projects need to be
+ * referred to for dependencies, paths, outputs etc.
+ * Projects is specifically an object stored in <root>/buildSrc/src/main/java/Config.kt
+ * It's a nullable variable, but we just store it here and use it elsewhere.
+ */
 Projects.core = project("core")
 Projects.bukkit = project("bukkit")
 Projects.sponge = project("sponge")
+/*
+Declares the various other projects and stores them to Gradle's `extra` properties.
+These are potentially usable for other purposes, but for now, they're here only to
+declare the values for this root project's dependency (for shadowjar)
+ */
 var core: Project by extra { project("core") }
 val bukkit by extra { project("bukkit") }
 val bukkit_18 by extra { bukkit.project("1_8_8") }
@@ -27,49 +32,58 @@ val bukkit_113 by extra { bukkit.project("1_13") }
 val sponge by extra { project("sponge") }
 val sponge_7 by extra { sponge.project("api7") }
 
-val configurate by extra { ""}
-
 group = properties["pluginGroup"]!!
 version = properties["pluginVersion"]!!
 
+/*
+Even though all projects declares some of these plugins, we want to declare them the traditional
+way so that we can have IDE utiliziation and processing, it helps with writing these scripts.
+ */
 plugins {
     `java-library`
     `maven-publish`
     id("com.github.johnrengelman.shadow") version "4.0.4"
 }
 
-configurations {
-    create("childJars")
-}
-val childJars: Configuration by configurations
-
-
-// Set up defaults for all projects, maven repositories, java compatibility level and compiling encoding
+/*
+Default management for ALL projects, not just root, or ":bukkit", but all projects and
+their children projects.
+ */
 allprojects {
+    /*
+    We need the java library processing, and shadow allows us to run
+    shadowJar to relocate dependencies and bundle dependencies into a fat jar.
+     */
     apply(plugin="java-library")
     apply(plugin="com.github.johnrengelman.shadow")
 
+    /*
+    Defines all the repositories for all project dependency resolutions. Some of these
+    repositories are meant for specific dependencies, so the content filters will
+    prevent attempts at resolving those dependencies being requested at those repositories.
+    Constants are defined in <root>/buildSrc/src/main/java/Config.kt
+     */
     repositories {
         mavenCentral()
-        // World Edit
-        maven(Repos.sk89q)
-        // bStats
-        maven(Repos.bstats)
-        // configurate
-        maven(Repos.sponge)
-        // spigot
-        maven(Repos.spigot)
-        maven(Repos.sonatype)
-        mavenLocal()
+        maven(Repos.sk89q) // WorldEdit/WorldGuard
+        maven(Repos.bstats) // bstats
+        maven(Repos.sponge) // Sponge, Configurate, and some other things
+        maven(Repos.spigot) // Spigot and Bukkit
+        maven(Repos.sonatype) // General Maven
+        mavenLocal() // For nms packages
     }
 
+    // Sets all projects compatibility level to Java 8
     java {
         sourceCompatibility = JavaVersion.VERSION_1_8
         targetCompatibility = JavaVersion.VERSION_1_8
     }
+    // Encoding for all packages is UTF-8
     tasks.getting(JavaCompile::class) {
         options.encoding = "UTF-8"
     }
+    // Default shadow jar configuration. Sub projects will override and add on,
+    // but this sets up at the very least the jdbc connection dependencies to be relocated
     val shadowJar by tasks.getting(ShadowJar::class) { // Configure basics of relocation
         relocate(Shadow.Origin.juli, Shadow.Target.juli)
         relocate(Shadow.Origin.tomcat, Shadow.Target.tomcat)
@@ -79,7 +93,13 @@ allprojects {
 
 }
 
-// Sub projects don't need to shadow their dependencies. This eliminates common ones
+/*
+All subprojects shadowjar tasks that will exclude various dependencies, while
+the root project will include some of these dependencies (like jdbc, configurate)
+so that the sub project jars are already somewhat minimized, in the event those
+platform jars are to be deployed individually versus an overall "all platforms"
+jar.
+ */
 subprojects {
     val shadowJar by tasks.getting(ShadowJar::class) {
         dependencies {
@@ -92,6 +112,9 @@ subprojects {
     }
 }
 
+// Sets up this root project to depend on all the implementations supported.
+// By default, they all already should have shadow relocations and packaging,
+// and their dependencies should not be leaking into this project.
 dependencies {
     compile(bukkit)
     compile(sponge)
@@ -100,6 +123,9 @@ dependencies {
     compile(bukkit_113)
     compile(sponge_7)
 }
+
+// Configure shadow for the root project, we want to relocate bstats-bukkit
+// and whatever else is configured in the allProjects configuration
 val shadowJar by tasks.getting(ShadowJar::class) { // Root shadow relocation
 
     relocate(Shadow.Origin.bstatsBukkit, Shadow.Target.bstatsBukkit)
@@ -107,5 +133,7 @@ val shadowJar by tasks.getting(ShadowJar::class) { // Root shadow relocation
     baseName = "mcMMO"
     classifier = "bundle"
 }
+
+// Tell the build task to depend on shadowjar.
 val build by tasks
 build.dependsOn(shadowJar)

bukkit/1_12/build.gradle.kts

@@ -1,12 +1,27 @@
 import Config.Libs.Bukkit.`1_12` as Bukkit
+// Config is located in <root>/buildSrc/src/main/java/Config.kt
+// It provides a bunch of constant values we use as dependency
+// strings, so we don't have to duplicate a bunch of them in
+// various scripts.
 
 plugins {
-    java
+    java // This is already provided, but for static compilation,
+    // we declare it here so we can use the IDE static type references
 }
 
+/*
+ Dependency inheritance is as follows
+  - ":core", which provides
+ configurate, tomcat jdbc/juli, and flowmath. It excludes sub
+ dependencies like guava and apache commons lang.
+  - ":bukkit", which provides nothing on it's own, except the
+ core bukkit classes that can be built on 1.13.2 API (which may change).
+ It also defines all subprojects to depend on ":core", and ":bukkit",
+ and bstats-bukkit.
+  */
 dependencies {
-    compileOnly(Bukkit.api) // Bukkit API
-    compileOnly(Bukkit.nms)
-    compileOnly(Bukkit.wgLegacy) // WorldGuard
+    compileOnly(Bukkit.api) // Bukkit API for 1.12.2
+    compileOnly(Bukkit.nms) // CraftBukkit for 1.12.2
+    compileOnly(Bukkit.wgLegacy) // WorldGuard for 1.12.2 bukkit
 
 }

bukkit/1_13/build.gradle.kts

@@ -1,12 +1,27 @@
 import Config.Libs.Bukkit.`1_13` as Bukkit
+// Config is located in <root>/buildSrc/src/main/java/Config.kt
+// It provides a bunch of constant values we use as dependency
+// strings, so we don't have to duplicate a bunch of them in
+// various scripts. The import allows us to "import as" for shorthand
 
 plugins {
-    `java-library`
+    `java-library` // This is already provided, but for static compilation,
+    // we declare it here so we can use the IDE static type references
 }
 
+/*
+ Dependency inheritance is as follows
+  - ":core", which provides
+ configurate, tomcat jdbc/juli, and flowmath. It excludes sub
+ dependencies like guava and apache commons lang.
+  - ":bukkit", which provides nothing on it's own, except the
+ core bukkit classes that can be built on 1.13.2 API (which may change).
+ It also defines all subprojects to depend on ":core", and ":bukkit",
+ and bstats-bukkit.
+  */
 dependencies {
-    compileOnly(Bukkit.api) // Bukkit API
-    compileOnly(Bukkit.nms)
-    compileOnly(Bukkit.wgCore) // WorldGuard
-    compileOnly(Bukkit.wgLegacy) // WG for Bukkit
+    compileOnly(Bukkit.api) // Bukkit API for 1.13.2 - Defined in <root>/buildSrc/src/main/java/Config.kt
+    compileOnly(Bukkit.nms) // CraftBukkit-1.13.2-R0.1-SNAPSHOT - Defined in <root>/buildSrc/src/main/java/Config.kt
+    compileOnly(Bukkit.wgCore) // WorldGuard-core - Defined in <root>/buildSrc/src/main/java/Config.kt
+    compileOnly(Bukkit.wgLegacy) // WorldGuard-legacy - Defined in <root>/buildSrc/src/main/java/Config.kt
 }

bukkit/1_8_8/build.gradle.kts

@@ -4,9 +4,20 @@ plugins {
     java
 }
 
+
+/*
+ Dependency inheritance is as follows
+  - ":core", which provides
+ configurate, tomcat jdbc/juli, and flowmath. It excludes sub
+ dependencies like guava and apache commons lang.
+  - ":bukkit", which provides nothing on it's own, except the
+ core bukkit classes that can be built on 1.13.2 API (which may change).
+ It also defines all subprojects to depend on ":core", and ":bukkit",
+ and bstats-bukkit.
+  */
 dependencies {
-    compileOnly(Bukkit.api) // Spigot API
-    compileOnly(Bukkit.wgLegacy) // Old worldguard
-    compileOnly(Bukkit.nms)
+    compileOnly(Bukkit.api) // Bukkit API for 1.8.8 - Defined in <root>/buildSrc/src/main/java/Config.kt
+    compileOnly(Bukkit.nms) // CraftBukkit-1.8.8-R0.3-SNAPSHOT - Defined in <root>/buildSrc/src/main/java/Config.kt
+    compileOnly(Bukkit.wgLegacy) // Old worldguard - Defined in <root>/buildSrc/src/main/java/Config.kt
 
 }

bukkit/build.gradle.kts

@@ -1,9 +1,21 @@
 import com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar
 import Config.Libs.Bukkit as Bukkit
+// Config is located in <root>/buildSrc/src/main/java/Config.kt
+// It provides a bunch of constant values we use as dependency
+// strings, so we don't have to duplicate a bunch of them in
+// various scripts. The import as allows for shorthand.
 
-val bukkit: Project = Projects.bukkit!!
-val core: Project = Projects.core!!
+val bukkit: Project = Projects.bukkit!! // Static project references
+val core: Project = Projects.core!! // Stored by Config.kt and created in <root>/build.gradle.kts
 
+/* This configures ":bukkit" and it's dependent projects:
+   - ":bukkit:1_8_8"
+   - ":bukkit:1_12"
+   - ":bukkit:1_13"
+   Basically sets up all projects to depend on ":core" and
+   bstats-bukkit. Also sets up shadow to relocate bukkit related
+   packages to limit platform interference
+ */
 allprojects {
 
     dependencies {
@@ -13,13 +25,20 @@ allprojects {
 
     // TODO dunno if this works yet... project needs to compile.
     val shadowJar by tasks.getting(ShadowJar::class) {
+        // Relocate bstats for bukkit, as per requirement for bstats
         relocate(Shadow.Origin.bstatsBukkit, Shadow.Target.bstatsBukkit)
+        // Relocate the bukkit platform classes of mcmmo so we don't
+        // interfere with other platform classes (or core)
         relocate(Deps.Groups.nossr, "${Deps.Groups.nossr}.bukkit") {
             exclude("${Deps.Groups.nossr}.core")
         }
     }
 }
 
+// Tells all subprojects of ":bukkit" (":bukkit:1_8_8", ":bukkit:1_12",etc.)
+// to depend on this project (":bukkit") to inherit the dependencies, and
+// does NOT inherit the same configurations (anything configured outside
+// here does not persist to child projects).
 subprojects {
     dependencies {
         // Provide the base bukkit plugin dependency for plugin classloading.
@@ -28,19 +47,20 @@ subprojects {
     }
 }
 plugins {
-    java
+    `java-library` // This is already provided, but for static compilation,
+    // we declare it here so we can use the IDE static type references
 }
 dependencies {
     // Temporary dependencies while things are being moved.
-    compileOnly(Bukkit.`1_13`.spigotApi) { // Spigot API
-        isTransitive = true
+    compileOnly(Bukkit.`1_13`.spigotApi) { // Spigot API for generic usage. Based on 1.13.2
+        isTransitive = true // We don't want the dependencies
     }
-    compileOnly(Bukkit.`1_13`.api) { // Spigot API
-        isTransitive = true
+    compileOnly(Bukkit.`1_13`.api) { // Bukkit API for generic usage. Based on 1.13.2
+        isTransitive = true // We don't want the dependencies
 
     }
-    compileOnly(Bukkit.`1_13`.wgCore) {
-        isTransitive = true
+    compileOnly(Bukkit.`1_13`.wgCore) { // WorldGuard dependency, again, for 1.13.2
+        isTransitive = true // We don't want the dependencies
         exclude(group = Shadow.Exclude.sk89q)
         exclude(group = Shadow.Exclude.intake, module = "intake")
         exclude(group = Shadow.Exclude.sk89q, module = "squirrelid")
@@ -49,7 +69,7 @@ dependencies {
         exclude(group = Shadow.Exclude.findbugs)
     }
     compileOnly(Bukkit.`1_13`.wgLegacy) {
-        isTransitive = true
+        isTransitive = true // We don't want the dependencies
         exclude(group = Shadow.Exclude.bukkit)
         exclude(group = Shadow.Exclude.sk89q, module = "commandbook")
         exclude(group = Shadow.Exclude.bstats)

core/build.gradle.kts

@@ -1,23 +1,27 @@
 import Config.Libs as Libs
+// Config is located in <root>/buildSrc/src/main/java/Config.kt
+// It provides a bunch of constant values we use as dependency
+// strings, so we don't have to duplicate a bunch of them in
+// various scripts. The import as allows for shorthand.
 
 plugins {
-    `java-library`
-    id("com.github.johnrengelman.shadow")
+    `java-library` // This is already provided, but for static compilation,
+    // we declare it here so we can use the IDE static type references
 }
 
 dependencies {
 
-    compile(Libs.configurate) {
-        exclude(Deps.Groups.guava, Deps.Modules.guava)
-        exclude(Deps.Groups.checker, Deps.Modules.checker)
+    compile(Libs.configurate) { // Configurate-Yaml dependency, inherits Configurate-core
+        exclude(Deps.Groups.guava, Deps.Modules.guava) // Exclude guava
+        exclude(Deps.Groups.checker, Deps.Modules.checker) // Exclude checkerframework
     }
-    compile(Libs.flowmath)
-    compile(Libs.jdbc)
-    compile(Libs.juli)
-    testCompile(Libs.junitDep)
+    compile(Libs.flowmath) // flowpowered math, for more maths.
+    compile(Libs.jdbc) // Database connectors
+    compile(Libs.juli) // Database connectors
+    testCompile(Libs.junitDep) // junit for testing
 
     // Spigot for in-dev dependency
-    compileOnly(Libs.Bukkit.`1_13`.spigotApi) {
-        isTransitive = false
+    compileOnly(Libs.Bukkit.`1_13`.spigotApi) { // Spigot only for temporary usage in core
+        isTransitive = false // Don't include spigot api's dependencies
     }
 }

sponge/api7/build.gradle.kts

@@ -1,6 +1,15 @@
 import net.minecraftforge.gradle.user.UserBaseExtension
 import Config.Libs.Sponge.API7 as API7
+// Config is located in <root>/buildSrc/src/main/java/Config.kt
+// It provides a bunch of constant values we use as dependency
+// strings, so we don't have to duplicate a bunch of them in
+// various scripts. The import as allows for shorthand.
 
+/*
+Special dependency for the buildscript to be able to use ForgeGradle 2.3-SNAPSHOT.
+Needs to define the repository where FG exists, and then adds the classpath of the
+plugin jar for the buildscript. It's what allows us to import UserBaseExtension
+ */
 buildscript {
     repositories {
         jcenter()
@@ -10,27 +19,43 @@ buildscript {
         classpath(Plugins.FG2_3.classpath)
     }
 }
-// Extension created to set up the minecraft block for ForgeGradle. This should change in FG3.
+
+// Extension created to set up the minecraft block for ForgeGradle. This will be different for ForgeGradle 3>, but we don't
+// use that newer version for 1.12, that will be used for 1.13+
 val Project.minecraft: UserBaseExtension
     get() = extensions.getByName<UserBaseExtension>(Plugins.FG2_3.extensionName)
 
 plugins {
     `java-library`
-    // Apply the spongegradle plugin to generate the metadata file
+    // Apply the spongegradle plugin to generate the metadata file, these cannot be import shorthanded because
+    // they need to be resolved at script compilation time to apply the plugin
     id(Config.Libs.Sponge.API7.spongeGradleId) version Config.Libs.Sponge.API7.spongeGradleVersion // supplies sponge repo and plugin metadata creation tasks
 }
+
+// Apply the FG2.3 plguin the old way, because there's no valid way to do it the new plugins way.
 apply(plugin = API7.forgeGradleId)
 
 dependencies {
+    // Only SpongeAPI needed for the base plugin class, a majority will be api version dependent.
     compileOnly(API7.api)  // SpongeAPI
 }
 
+/*
+Now this configures ForgeGradle to set up the Minecraft (NMS) dependency. To use it, one needs to run
+`gradlew sDecW` either from root or `gradlew :sponge:api7:sDecW`. The process generates a Minecraft
+dependency with forge sources so one can read MCP remapped code. The dependency is not included in
+git.
+ */
 configure<UserBaseExtension> {
-    version = API7.minecraftVersion
-    runDir = "run"
-    mappings = API7.mappings
+    version = API7.minecraftVersion // The minecraft (forge) version
+    runDir = "run" // Where the run directory will be placed
+    mappings = API7.mappings // The MCP mappings version
 }
 
+/**
+ * Some extra information that needs to be included for plugin/mod generation that will be
+ * parsed by Sponge or Forge (when SpongeForge is involved, Forge loads the plugins for SpongeForge)
+ */
 tasks.withType<Jar> {
     inputs.properties += "version" to project.version
     inputs.properties += "mcversion" to project.minecraft.version

sponge/api7/gradle.properties

@@ -1,3 +0,0 @@
-mod_name = "mcmmo"
-mod_version = "2.2-SNAPSHOT"
-mc_version = "1.12.2"

sponge/build.gradle.kts

@@ -1,8 +1,13 @@
 import com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar
 import Config.Libs.Sponge as Sponge
+// Config is located in <root>/buildSrc/src/main/java/Config.kt
+// It provides a bunch of constant values we use as dependency
+// strings, so we don't have to duplicate a bunch of them in
+// various scripts. The import as allows for shorthand.
 
 plugins {
-    java
+    `java-library` // This is already provided, but for static compilation,
+    // we declare it here so we can use the IDE static type references
 }
 
 val core = Projects.core!! // because it's a var and potentially null by declaration
@@ -10,23 +15,36 @@ val sponge = Projects.sponge!! // because it's a var and potentially null by dec
 
 description = "mcMMO for Sponge"
 
+/*
+These dependencies are minimalized. SpongeAPI is not inherited by subprojects.
+Bstats-sponge is api version agnostic for the moment.
+ */
 dependencies {
     compile(Sponge.bstats) // Bstats is used for all sponge versions
-    compileOnly(Sponge.API7.api) // Base version
+    compileOnly(Sponge.API7.api) // Base version for common plugin class
 }
 
+/* This configures ":sponge" and it's dependent projects:
+   - ":sponge:api7"
+   Basically sets up all projects to depend on ":core" and
+   bstats-sponge. Bstatss-sponge should not be relocated
+ */
 allprojects {
     dependencies {
         compile(Projects.core!!)
     }
     // TODO dunno if this works yet... project needs to compile.
-    val shadowJar by tasks.getting(ShadowJar::class) {
+    val shadowJar by tasks.getting(ShadowJar::class) { // We set this up so we relocate all sponge projects, not just ":sponge"
         relocate(Deps.Groups.nossr, "${Deps.Groups.nossr}.sponge") {
             exclude("${Deps.Groups.nossr}.core")
         }
     }
 }
 
+// Tells all subprojects of ":sponge" (":sponge:api7")
+// to depend on this project (":sponge") to inherit the dependencies, and
+// does NOT inherit the same configurations (anything configured outside
+// here does not persist to child projects).
 subprojects {
     dependencies {
         (compileOnly(sponge) as ModuleDependency).apply {