From de339b3ad34612cbf5bb430f783b04f781cdbf47 Mon Sep 17 00:00:00 2001 From: liach <7806504+liach@users.noreply.github.com> Date: Wed, 31 Mar 2021 04:39:16 +0700 Subject: [PATCH] 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 * Apply suggestions from code review Co-authored-by: Joseph Burton Co-authored-by: Juuxel <6596629+Juuxel@users.noreply.github.com> Co-authored-by: liach Co-authored-by: Joseph Burton Co-authored-by: Juuxel <6596629+Juuxel@users.noreply.github.com> --- build.gradle | 21 +++++- .../java/net/minecraft/package-info.java | 17 +++++ .../net/minecraft/resource/package-info.java | 72 +++++++++++++++++++ 3 files changed, 107 insertions(+), 3 deletions(-) create mode 100644 src/packageDocs/java/net/minecraft/package-info.java create mode 100644 src/packageDocs/java/net/minecraft/resource/package-info.java diff --git a/build.gradle b/build.gradle index 1fdfda9d99..eef90e4c92 100644 --- a/build.gradle +++ b/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 { diff --git a/src/packageDocs/java/net/minecraft/package-info.java b/src/packageDocs/java/net/minecraft/package-info.java new file mode 100644 index 0000000000..e8a1711263 --- /dev/null +++ b/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. + * + *

Unmapped classes go into this package by default. This package additionally contains + * {@link Bootstrap}, {@link SharedConstants}, and {@link MinecraftVersion} classes. + * + *

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; diff --git a/src/packageDocs/java/net/minecraft/resource/package-info.java b/src/packageDocs/java/net/minecraft/resource/package-info.java new file mode 100644 index 0000000000..a257a46fb2 --- /dev/null +++ b/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. + * + *

"Data" as in "Data Packs" is considered resource as well. + * + *

Here is a quick overview on the resource access and provision APIs of Minecraft: + *

+ * + * + * + * + * + * + * + * + * + * + * + + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Resource Access APIs
ClassUsage
{@link Resource}Accesses binary data.
{@link ResourceFactory}Provides a resource given an {@link net.minecraft.util.Identifier}.
{@link ResourceManager}Exposes more resource access in addition to being a {@link ResourceFactory}.
{@link ResourceReloader}The most common accessor to resources, acting during "reloads" to set up in-game contents. + *
This is usually implemented by mods using resources.
{@link ReloadableResourceManager}Performs reloads and manages {@link ResourceReloader}s in addition to being a {@link ResourceManager}. + *
Usually held by the game engine, it may be provided by the modding APIs as well.
+ * + *
+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Resource Provision APIs
ClassUsage
{@link ResourcePack}Provides binary data based on queries. + *
They are usually single-use, created by {@link ResourcePackManager} and provided + * to {@link ReloadableResourceManager} in each reload.
{@link ResourcePackProfile}A user-friendly, persistent form of {@link ResourcePack}. Used to create resource + * packs in reloads.
{@link ResourcePackProvider}Provides {@link ResourcePackProfile}s, so they are taken account of during reloads. + *
This is usually implemented by mods providing resources.
{@link ResourcePackManager}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.
+ * + *

In addition to these APIs, this package includes implementation details of the resource system. + */ + +package net.minecraft.resource;