Clean up Javadocs a little

I've no motivation for modding right now, but always got time for build
system busywork!

CC:T (and CC before that) has always published its API docs. However,
they're not always the most helpful — they're useful if you know what
you're looking for, but aren't a good getting-started guide.

Part of the issue here is there's no examples, and everything is
described pretty abstractly. I have occasionally tried to improve this
(e.g. the peripheral docs in bdffabc08e),
but it's a long road.

This commit adds a new example mod, which registers peripherals, an API
and a turtle upgrade. While the mod itself isn't exported as part of the
docs, we reference blocks of it using Java's new {@snippet} tag.

 - Switch the Forge project to use NeoForge's new Legacy MDG plugin. We
   don't *need* to do this, but it means the build logic for Forge and
   NeoForge is more closely aligned.

 - Add a new SnippetTaglet, which is a partial backport of Java 18+'s
   {@snippet}.

 - Add an example mod. This is a working multi-loader mod, complete with
   datagen (albeit with no good multi-loader abstractions).

 - Move our existing <pre>{@code ...}</pre> blocks into the example mod,
   replacing them with {@snippet}s.

 - Add a new overview page to the docs, providing some getting-started
   information. We had this already in the dan200.computercraft.api
   package docs, but it's not especially visible there.

projects/common-api/build.gradle.kts

@@ -18,13 +18,28 @@ dependencies {
     api(project(":core-api"))
 }
 
+val javadocOverview by tasks.registering(Copy::class) {
+    from("src/overview.html")
+    into(layout.buildDirectory.dir(name))
+
+    expand(
+        mapOf(
+            "mcVersion" to mcVersion,
+            "modVersion" to version,
+        ),
+    )
+}
+
 tasks.javadoc {
-    title = "CC: Tweaked $version Minecraft $mcVersion"
+    title = "CC: Tweaked $version for Minecraft $mcVersion"
     include("dan200/computercraft/api/**/*.java")
 
     options {
         (this as StandardJavadocDocletOptions)
 
+        inputs.files(javadocOverview)
+        overview(javadocOverview.get().destinationDir.resolve("overview.html").absolutePath)
+
         groups = mapOf(
             "Common" to listOf(
                 "dan200.computercraft.api",
@@ -47,6 +62,15 @@ tasks.javadoc {
             <link href=" https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism.min.css " rel="stylesheet">
             """.trimIndent(),
         )
+
+        taglets("cc.tweaked.javadoc.SnippetTaglet")
+        tagletPath(configurations.detachedConfiguration(dependencies.project(":lints")).toList())
+
+        val snippetSources = listOf(":common", ":fabric", ":forge").flatMap {
+            project(it).sourceSets["examples"].allSource.sourceDirectories
+        }
+        inputs.files(snippetSources)
+        jFlags("-Dcc.snippet-path=" + snippetSources.joinToString(File.pathSeparator) { it.absolutePath })
     }
 
     // Include the core-api in our javadoc export. This is wrong, but it means we can export a single javadoc dump.

projects/common-api/src/client/java/dan200/computercraft/api/client/turtle/TurtleUpgradeModeller.java

@@ -22,7 +22,14 @@ import java.util.List;
  * <p>
  * Use {@code dan200.computercraft.api.client.FabricComputerCraftAPIClient#registerTurtleUpgradeModeller} to register a
  * modeller on Fabric and {@code dan200.computercraft.api.client.turtle.RegisterTurtleModellersEvent} to register one
- * on Forge
+ * on Forge.
+ *
+ * <h2>Example</h2>
+ * <h3>Fabric</h3>
+ * {@snippet class=com.example.examplemod.FabricExampleModClient region=turtle_modellers}
+ *
+ * <h3>Forge</h3>
+ * {@snippet class=com.example.examplemod.FabricExampleModClient region=turtle_modellers}
  *
  * @param <T> The type of turtle upgrade this modeller applies to.
  * @see RegisterTurtleUpgradeModeller For multi-loader registration support.

projects/common-api/src/main/java/dan200/computercraft/api/ComputerCraftAPI.java

@@ -171,16 +171,9 @@ public final class ComputerCraftAPI {
      * using {@link ILuaAPI#getModuleName()} to expose this library as a module instead of as a global.
      * <p>
      * This may be used with {@link IComputerSystem#getComponent(ComputerComponent)} to only attach APIs to specific
-     * computers. For example, one can add an additional API just to turtles with the following code:
+     * computers. For example, one can add a new API just to turtles with the following code:
      *
-     * <pre class="language language-java">{@code
-     * ComputerCraftAPI.registerAPIFactory(computer -> {
-     *   // Read the turtle component.
-     *   var turtle = computer.getComponent(ComputerComponents.TURTLE);
-     *   // If present then add our API.
-     *   return turtle == null ? null : new MyCustomTurtleApi(turtle);
-     * });
-     * }</pre>
+     * {@snippet class=com.example.examplemod.ExampleAPI region=register}
      *
      * @param factory The factory for your API subclass.
      * @see ILuaAPIFactory

projects/common-api/src/main/java/dan200/computercraft/api/pocket/IPocketUpgrade.java

@@ -14,13 +14,10 @@ import javax.annotation.Nullable;
  * A peripheral which can be equipped to the back side of a pocket computer.
  * <p>
  * Pocket upgrades are defined in two stages. First, on creates a {@link IPocketUpgrade} subclass and corresponding
- * {@link PocketUpgradeSerialiser} instance, which are then registered in a Forge registry.
+ * {@link PocketUpgradeSerialiser} instance, which are then registered in a Minecraft registry.
  * <p>
  * You then write a JSON file in your mod's {@literal data/} folder. This is then parsed when the world is loaded, and
- * the upgrade registered internally. See the documentation in {@link PocketUpgradeSerialiser} for details on this process
- * and where files should be located.
- *
- * @see PocketUpgradeSerialiser For how to register a pocket computer upgrade.
+ * the upgrade registered internally.
  */
 public interface IPocketUpgrade extends UpgradeBase {
     /**

projects/common-api/src/main/java/dan200/computercraft/api/turtle/ITurtleUpgrade.java

@@ -8,21 +8,69 @@ import dan200.computercraft.api.peripheral.IPeripheral;
 import dan200.computercraft.api.upgrades.UpgradeBase;
 import net.minecraft.core.Direction;
 import net.minecraft.nbt.CompoundTag;
+import net.minecraft.world.item.Items;
 
 import javax.annotation.Nullable;
+import java.util.function.BiFunction;
 
 /**
  * The primary interface for defining an update for Turtles. A turtle update can either be a new tool, or a new
  * peripheral.
  * <p>
  * Turtle upgrades are defined in two stages. First, one creates a {@link ITurtleUpgrade} subclass and corresponding
- * {@link TurtleUpgradeSerialiser} instance, which are then registered in a Forge registry.
+ * {@link TurtleUpgradeSerialiser} instance, which are then registered in a Minecraft registry.
  * <p>
  * You then write a JSON file in your mod's {@literal data/} folder. This is then parsed when the world is loaded, and
- * the upgrade registered internally. See the documentation in {@link TurtleUpgradeSerialiser} for details on this process
- * and where files should be located.
+ * the upgrade automatically registered.
  *
- * @see TurtleUpgradeSerialiser For how to register a turtle upgrade.
+ * <h2>Example</h2>
+ * <h3>Registering the upgrade serialiser</h3>
+ * First, let's create a new class that implements {@link ITurtleUpgrade}. It is recommended to subclass
+ * {@link AbstractTurtleUpgrade}, as that provides a default implementation of most methods.
+ * <p>
+ * {@snippet class=com.example.examplemod.ExampleTurtleUpgrade region=body}
+ * <p>
+ * Now we must construct a new upgrade serialiser. In most cases, you can use one of the helper methods
+ * (e.g. {@link TurtleUpgradeSerialiser#simpleWithCustomItem(BiFunction)}), rather than defining your own implementation.
+ *
+ * {@snippet class=com.example.examplemod.ExampleMod region=turtle_upgrades}
+ *
+ * We now must register this upgrade serialiser. This is done the same way as you'd register blocks, items, or other
+ * Minecraft objects. The approach to do this will depend on mod-loader.
+ *
+ * <h4>Fabric</h4>
+ * {@snippet class=com.example.examplemod.FabricExampleMod region=turtle_upgrades}
+ *
+ * <h4>Forge</h4>
+ * {@snippet class=com.example.examplemod.ForgeExampleMod region=turtle_upgrades}
+ *
+ * <h3>Rendering the upgrade</h3>
+ * Next, we need to register a model for our upgrade. This is done by registering a
+ * {@link dan200.computercraft.api.client.turtle.TurtleUpgradeModeller} for your upgrade serialiser.
+ *
+ * <h4>Fabric</h4>
+ * {@snippet class=com.example.examplemod.FabricExampleModClient region=turtle_modellers}
+ *
+ *
+ * <h4>Forge</h4>
+ * {@snippet class=com.example.examplemod.FabricExampleModClient region=turtle_modellers}
+ *
+ * <h3>Registering the upgrade itself</h3>
+ * Upgrades themselves are loaded from datapacks when a level is loaded. In order to register our new upgrade, we must
+ * create a new JSON file at {@code data/<my_mod>/computercraft/turtle_upgrades/<my_upgrade_id>.json}.
+ *
+ * {@snippet file = data/examplemod/computercraft/turtle_upgrades/example_turtle_upgrade.json}
+ *
+ * The {@code "type"} field points to the ID of the upgrade serialiser we've just registered, while the other fields
+ * are read by the serialiser itself. As our upgrade was defined with {@link TurtleUpgradeSerialiser#simpleWithCustomItem(BiFunction)}, the
+ * {@code "item"} field will construct our upgrade with {@link Items#COMPASS}.
+ * <p>
+ * Rather than manually creating the file, it is recommended to data-generators to generate this file. This can be done
+ * with {@link TurtleUpgradeDataProvider}.
+ *
+ * {@snippet class=com.example.examplemod.data.TurtleDataProvider region=body}
+ *
+ * @see TurtleUpgradeSerialiser Registering a turtle upgrade.
  */
 public interface ITurtleUpgrade extends UpgradeBase {
     /**

projects/common-api/src/main/java/dan200/computercraft/api/turtle/TurtleUpgradeDataProvider.java

@@ -29,6 +29,9 @@ import java.util.function.Consumer;
  * {@link #addUpgrades(Consumer)} function, construct each upgrade, and pass them off to the provided consumer to
  * generate them.
  *
+ * <h2>Example</h2>
+ * {@snippet class=com.example.examplemod.data.TurtleDataProvider region=body}
+ *
  * @see TurtleUpgradeSerialiser
  */
 public abstract class TurtleUpgradeDataProvider extends UpgradeDataProvider<ITurtleUpgrade, TurtleUpgradeSerialiser<?>> {

projects/common-api/src/main/java/dan200/computercraft/api/turtle/TurtleUpgradeSerialiser.java

@@ -27,32 +27,6 @@ import java.util.function.Function;
  * If your turtle upgrade doesn't have any associated configurable parameters (like most upgrades), you can use
  * {@link #simple(Function)} or {@link #simpleWithCustomItem(BiFunction)} to create a basic upgrade serialiser.
  *
- * <h2>Example (Forge)</h2>
- * <pre class="language language-java">{@code
- * static final DeferredRegister<TurtleUpgradeSerialiser<?>> SERIALISERS = DeferredRegister.create( TurtleUpgradeSerialiser.TYPE, "my_mod" );
- *
- * // Register a new upgrade serialiser called "my_upgrade".
- * public static final RegistryObject<TurtleUpgradeSerialiser<MyUpgrade>> MY_UPGRADE =
- *     SERIALISERS.register( "my_upgrade", () -> TurtleUpgradeSerialiser.simple( MyUpgrade::new ) );
- *
- * // Then in your constructor
- * SERIALISERS.register( bus );
- * }</pre>
- * <p>
- * We can then define a new upgrade using JSON by placing the following in
- * {@literal data/<my_mod>/computercraft/turtle_upgrades/<my_upgrade_id>.json}}.
- *
- * <pre class="language language-json">{@code
- * {
- *     "type": "my_mod:my_upgrade",
- * }
- * }</pre>
- * <p>
- * Finally, we need to register a model for our upgrade. The way to do this varies on mod loader, see
- * {@link dan200.computercraft.api.client.turtle.TurtleUpgradeModeller} for more information.
- * <p>
- * {@link TurtleUpgradeDataProvider} provides a data provider to aid with generating these JSON files.
- *
  * @param <T> The type of turtle upgrade this is responsible for serialising.
  * @see ITurtleUpgrade
  * @see TurtleUpgradeDataProvider

projects/common-api/src/main/java/dan200/computercraft/api/upgrades/UpgradeDataProvider.java

@@ -32,6 +32,8 @@ import java.util.function.Function;
  *
  * @param <T> The base class of upgrades.
  * @param <R> The upgrade serialiser to register for.
+ * @see dan200.computercraft.api.turtle.TurtleUpgradeDataProvider
+ * @see dan200.computercraft.api.pocket.PocketUpgradeDataProvider
  */
 public abstract class UpgradeDataProvider<T extends UpgradeBase, R extends UpgradeSerialiser<? extends T>> implements DataProvider {
     private final PackOutput output;
@@ -84,13 +86,9 @@ public abstract class UpgradeDataProvider<T extends UpgradeBase, R extends Upgra
 
     /**
      * Add all turtle or pocket computer upgrades.
-     * <p>
-     * <strong>Example usage:</strong>
-     * <pre class="language language-java">{@code
-     * protected void addUpgrades(Consumer<Upgrade<TurtleUpgradeSerialiser<?>>> addUpgrade) {
-     *     simple(new ResourceLocation("mymod", "speaker"), SPEAKER_SERIALISER.get()).add(addUpgrade);
-     * }
-     * }</pre>
+     *
+     * <h4>Example</h4>
+     * {@snippet class=com.example.examplemod.data.TurtleDataProvider region=body}
      *
      * @param addUpgrade A callback used to register an upgrade.
      */

projects/common-api/src/overview.html

@@ -0,0 +1,68 @@
+<!--
+SPDX-FileCopyrightText: 2025 The CC: Tweaked Developers
+
+SPDX-License-Identifier: MPL-2.0
+-->
+
+<!DOCTYPE HTML>
+<html lang="en">
+<body>
+<p>
+    This is the documentation for CC: Tweaked $modVersion for Minecraft $mcVersion. Documentation for other versions of
+    Minecraft are available on the CC: Tweaked website:
+
+<ul>
+    <li><a href="/mc-1.20.x/javadoc/">Minecraft 1.20.1</a>
+    <li><a href="/mc-1.21.x/javadoc/">Minecraft 1.21.1</a>
+</ul>
+
+<h1>Quick links</h1>
+<p>
+    You probably want to start in the following places:
+
+<ul>
+    <li>{@linkplain dan200.computercraft.api.peripheral Registering new peripherals}</li>
+    <li>
+        {@link dan200.computercraft.api.lua.LuaFunction} and {@link dan200.computercraft.api.lua.IArguments} for
+        adding methods to your peripheral or Lua objects.
+    </li>
+    <li>{@linkplain dan200.computercraft.api.turtle.ITurtleUpgrade Turtle upgrades}</li>
+    <li>{@linkplain dan200.computercraft.api.pocket.IPocketUpgrade Pocket upgrades}</li>
+</ul>
+
+<h1>Using</h1>
+<p>
+    CC: Tweaked is hosted on my maven repo, and so is relatively simple to depend on. You may wish to add a soft (or
+    hard) dependency in your <code>mods.toml</code> file, with the appropriate version bounds, to ensure that API
+    functionality you depend on is present.
+
+<pre class="language language-groovy"><code>repositories {
+    maven {
+        url "https://maven.squiddev.cc"
+        content { includeGroup("cc.tweaked") }
+    }
+}
+
+dependencies {
+    // Vanilla (i.e. for multi-loader systems)
+    compileOnly("cc.tweaked:cc-tweaked-$mcVersion-common-api:$modVersion")
+
+    // Forge Gradle
+    compileOnly("cc.tweaked:cc-tweaked-$mcVersion-core-api:$modVersion")
+    compileOnly(fg.deobf("cc.tweaked:cc-tweaked-$mcVersion-forge-api:$modVersion"))
+    runtimeOnly(fg.deobf("cc.tweaked:cc-tweaked-$mcVersion-forge:$modVersion"))
+
+    // Fabric Loom
+    modCompileOnly("cc.tweaked:cc-tweaked-$mcVersion-fabric-api:$modVersion")
+    modRuntimeOnly("cc.tweaked:cc-tweaked-$mcVersion-fabric:$modVersion")
+}
+</code></pre>
+
+<p>
+    You should also be careful to only use classes within the <code>dan200.computercraft.api</code> package. Non-API
+    classes are subject to change at any point. If you depend on functionality outside the API (or need to mixin to
+    CC:T), please <a href="https://github.com/cc-tweaked/CC-Tweaked/discussions/new/choose">start a discussion</a> to
+    let me know!
+
+</body>
+</html>