Add package javadoc support (#2205)

* Add package javadoc support

Closes #2035

This is surprisingly easy given modmuss's work on constants. So here we go

Signed-off-by: liach <liach@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Joseph Burton <burtonjae@hotmail.co.uk>
Co-authored-by: Juuxel <6596629+Juuxel@users.noreply.github.com>

Co-authored-by: liach <liach@users.noreply.github.com>
Co-authored-by: Joseph Burton <burtonjae@hotmail.co.uk>
Co-authored-by: Juuxel <6596629+Juuxel@users.noreply.github.com>

build.gradle

@@ -415,7 +415,7 @@ task yarn(dependsOn: mapIntermediaryJar) {
 	}
 }
 
-task checkMappings {
+task checkMappings(dependsOn: mapIntermediaryJar) {
 	group = buildMappingGroup
 	inputs.dir mappingsDir
 	doLast {
@@ -744,11 +744,12 @@ tasks.withType(JavaCompile).configureEach {
 
 sourceSets {
 	constants
+	packageDocs // package info files
 }
 
 license {
 	header file("HEADER")
-	sourceSets = [sourceSets.constants]
+	sourceSets = [sourceSets.constants, sourceSets.packageDocs]
 	include '**/*.java'
 }
 
@@ -762,6 +763,20 @@ task sourcesJar(type: Jar, dependsOn: classes) {
 	from sourceSets.constants.allSource
 }
 
+compilePackageDocsJava {
+	it.options.encoding = "UTF-8"
+	// use java 11 as the package info files aren't consumed by downstream java 8 mods etc.
+	if (!JavaVersion.current().isCompatibleWith(JavaVersion.VERSION_11)) {
+		javaCompiler = javaToolchains.compilerFor {
+			languageVersion = JavaLanguageVersion.of(11)
+		}
+	}
+	it.options.release = 11
+}
+
+// Only build jars for package infos if we need to actually expose stuff like annotation in the future.
+// Also need to downgrade java in that case!
+
 build.dependsOn constantsJar
 
 task insertAutoGeneratedEnumMappings(dependsOn : [buildYarnTiny,mapIntermediaryJar], type : FileOutput){
@@ -940,7 +955,7 @@ javadoc {
 		addBooleanOption 'Xdoclint:reference', true
 		addBooleanOption 'Xdoclint:accessibility', true
 	}
-	source fileTree(fakeSourceDir) + sourceSets.constants.allJava
+	source fileTree(fakeSourceDir) + sourceSets.constants.allJava + sourceSets.packageDocs.allJava
 	classpath = configurations.javadocClasspath.plus downloadMcLibs.outputs.files.asFileTree
 
 	finalizedBy {

src/packageDocs/java/net/minecraft/package-info.java

@@ -0,0 +1,17 @@
+/*
+ * This file is free for everyone to use under the Creative Commons Zero license.
+ */
+
+/**
+ * The base package for all Minecraft classes. All Minecraft classes belong to this package
+ * in their intermediary names.
+ *
+ * <p>Unmapped classes go into this package by default. This package additionally contains
+ * {@link Bootstrap}, {@link SharedConstants}, and {@link MinecraftVersion} classes.
+ *
+ * <p>While it's known that some obfuscated Minecraft classes are under other packages like
+ * {@code com.mojang.*}, yarn keeps all mapped classes under {@code net.minecraft.*} since
+ * there is no convincing evidence those classes are independent from Minecraft.
+ */
+
+package net.minecraft;

src/packageDocs/java/net/minecraft/resource/package-info.java

@@ -0,0 +1,72 @@
+/*
+ * This file is free for everyone to use under the Creative Commons Zero license.
+ */
+
+/**
+ * Provides resources to Minecraft, including resource access and provision.
+ *
+ * <p>"Data" as in "Data Packs" is considered resource as well.
+ *
+ * <p>Here is a quick overview on the resource access and provision APIs of Minecraft:
+ * <div class="fabric" id="resource-access"><table border=1>
+ * <caption>Resource Access APIs</caption>
+ * <tr>
+ *     <th><b>Class</b></th><th><b>Usage</b></th>
+ * </tr>
+ * <tr>
+ *     <td>{@link Resource}</td>
+ *     <td>Accesses binary data.</td>
+ * </tr>
+ * <tr>
+ *     <td>{@link ResourceFactory}</td>
+ *     <td>Provides a resource given an {@link net.minecraft.util.Identifier}.</td>
+
+ * </tr>
+ * <tr>
+ *     <td>{@link ResourceManager}</td>
+ *     <td>Exposes more resource access in addition to being a {@link ResourceFactory}.</td>
+ * </tr>
+ * <tr>
+ *     <td>{@link ResourceReloader}</td>
+ *     <td>The most common accessor to resources, acting during "reloads" to set up in-game contents.
+ *     <br><i>This is usually implemented by mods using resources.</i></td>
+ * </tr>
+ * <tr>
+ *     <td>{@link ReloadableResourceManager}</td>
+ *     <td>Performs reloads and manages {@link ResourceReloader}s in addition to being a {@link ResourceManager}.
+ *     <br>Usually held by the game engine, it may be provided by the modding APIs as well.</td>
+ * </tr>
+ * </table></div>
+ *
+ * <div class="fabric" id="resource-provision"><table border=1>
+ * <caption>Resource Provision APIs</caption>
+ * <tr>
+ *     <th><b>Class</b></th><th><b>Usage</b></th>
+ * </tr>
+ * <tr>
+ *     <td>{@link ResourcePack}</td>
+ *     <td>Provides binary data based on queries.
+ *     <br>They are usually single-use, created by {@link ResourcePackManager} and provided
+ *     to {@link ReloadableResourceManager} in each reload.</td>
+ * </tr>
+ * <tr>
+ *     <td>{@link ResourcePackProfile}</td>
+ *     <td>A user-friendly, persistent form of {@link ResourcePack}. Used to create resource
+ *     packs in reloads.</td>
+ * </tr>
+ * <tr>
+ *     <td>{@link ResourcePackProvider}</td>
+ *     <td>Provides {@link ResourcePackProfile}s, so they are taken account of during reloads.
+ *     <br><i>This is usually implemented by mods providing resources.</i></td>
+ * </tr>
+ * <tr>
+ *     <td>{@link ResourcePackManager}</td>
+ *     <td>Keeps track of {@link ResourcePackProvider}s and uses the profiles from the providers
+ *     to create {@link ResourcePack}s to send to {@link ReloadableResourceManager}s in each reload.</td>
+ * </tr>
+ * </table></div>
+ *
+ * <p>In addition to these APIs, this package includes implementation details of the resource system.
+ */
+
+package net.minecraft.resource;