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/fabric/build.gradle.kts

@@ -106,8 +106,6 @@ dependencies {
     testFixturesImplementation(testFixtures(project(":core")))
 }
 
-sourceSets.main { resources.srcDir("src/generated/resources") }
-
 loom {
     accessWidenerPath.set(project(":common").file("src/main/resources/computercraft.accesswidener"))
     mixin.defaultRefmapName.set("computercraft.refmap.json")
@@ -126,6 +124,10 @@ loom {
             sourceSet(sourceSets.testMod.get())
             sourceSet(project(":common").sourceSets.testMod.get())
         }
+
+        register("examplemod") {
+            sourceSet(sourceSets.examples.get())
+        }
     }
 
     runs {
@@ -142,19 +144,24 @@ loom {
             runDir("run/server")
         }
 
-        register("data") {
-            configName = "Datagen"
+        fun RunConfigSettings.configureForData(sourceSet: SourceSet) {
             client()
-
-            source(sourceSets.datagen.get())
-
-            runDir("run/dataGen")
+            runDir("run/run${name.capitalise()}")
             property("fabric-api.datagen")
-            property("fabric-api.datagen.output-dir", layout.buildDirectory.dir("generatedResources").getAbsolutePath())
+            property(
+                "fabric-api.datagen.output-dir",
+                layout.buildDirectory.dir(sourceSet.getTaskName("generateResources", null)).getAbsolutePath(),
+            )
             property("fabric-api.datagen.strict-validation")
         }
 
-        fun configureForGameTest(config: RunConfigSettings) = config.run {
+        register("data") {
+            configName = "Datagen"
+            configureForData(sourceSets.main.get())
+            source(sourceSets.datagen.get())
+        }
+
+        fun RunConfigSettings.configureForGameTest() {
             source(sourceSets.testMod.get())
 
             val testSources = project(":common").file("src/testMod/resources/data/cctest").absolutePath
@@ -169,7 +176,7 @@ loom {
         val testClient by registering {
             configName = "Test Client"
             client()
-            configureForGameTest(this)
+            configureForGameTest()
 
             runDir("run/testClient")
             property("cctest.tags", "client,common")
@@ -178,16 +185,27 @@ loom {
         register("gametest") {
             configName = "Game Test"
             server()
-            configureForGameTest(this)
+            configureForGameTest()
 
             property("fabric-api.gametest")
             property(
                 "fabric-api.gametest.report-file",
-                layout.buildDirectory.dir("test-results/runGametest.xml")
-                    .getAbsolutePath(),
+                layout.buildDirectory.dir("test-results/runGametest.xml").getAbsolutePath(),
             )
             runDir("run/gametest")
         }
+
+        register("exampleClient") {
+            client()
+            configName = "Example Mod Client"
+            source(sourceSets.examples.get())
+        }
+
+        register("exampleData") {
+            configName = "Example Mod Datagen"
+            configureForData(sourceSets.examples.get())
+            source(sourceSets.examples.get())
+        }
     }
 }
 

projects/fabric/src/examples/java/com/example/examplemod/FabricExampleMod.java

@@ -0,0 +1,30 @@
+package com.example.examplemod;
+
+import com.example.examplemod.peripheral.BrewingStandPeripheral;
+import dan200.computercraft.api.peripheral.PeripheralLookup;
+import dan200.computercraft.api.turtle.TurtleUpgradeSerialiser;
+import net.fabricmc.api.ModInitializer;
+import net.minecraft.core.Registry;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.resources.ResourceLocation;
+import net.minecraft.world.level.block.entity.BlockEntityType;
+
+/**
+ * The main entry point for our example mod.
+ */
+public class FabricExampleMod implements ModInitializer {
+    @Override
+    public void onInitialize() {
+        // @start region=turtle_upgrades
+        @SuppressWarnings("unchecked")
+        var turtleUpgradeSerialisers = (Registry<TurtleUpgradeSerialiser<?>>) BuiltInRegistries.REGISTRY.get(TurtleUpgradeSerialiser.registryId().location());
+        Registry.register(turtleUpgradeSerialisers, new ResourceLocation(ExampleMod.MOD_ID, "example_turtle_upgrade"), ExampleMod.EXAMPLE_TURTLE_UPGRADE);
+        // @end region=turtle_upgrades
+
+        ExampleMod.registerComputerCraft();
+
+        // @start region=peripherals
+        PeripheralLookup.get().registerForBlockEntity((f, s) -> new BrewingStandPeripheral(f), BlockEntityType.BREWING_STAND);
+        // @end region=peripherals
+    }
+}

projects/fabric/src/examples/java/com/example/examplemod/FabricExampleModClient.java

@@ -0,0 +1,14 @@
+package com.example.examplemod;
+
+import dan200.computercraft.api.client.FabricComputerCraftAPIClient;
+import dan200.computercraft.api.client.turtle.TurtleUpgradeModeller;
+import net.fabricmc.api.ClientModInitializer;
+
+public class FabricExampleModClient implements ClientModInitializer {
+    @Override
+    public void onInitializeClient() {
+        // @start region=turtle_modellers
+        FabricComputerCraftAPIClient.registerTurtleUpgradeModeller(ExampleMod.EXAMPLE_TURTLE_UPGRADE, TurtleUpgradeModeller.flatItem());
+        // @end region=turtle_modellers
+    }
+}

projects/fabric/src/examples/java/com/example/examplemod/FabricExampleModDataGenerator.java

@@ -0,0 +1,17 @@
+package com.example.examplemod;
+
+import com.example.examplemod.data.TurtleDataProvider;
+import net.fabricmc.fabric.api.datagen.v1.DataGeneratorEntrypoint;
+import net.fabricmc.fabric.api.datagen.v1.FabricDataGenerator;
+import net.minecraft.data.DataProvider;
+
+/**
+ * The data generator entrypoint for our Fabric example mod.
+ */
+public class FabricExampleModDataGenerator implements DataGeneratorEntrypoint {
+    @Override
+    public void onInitializeDataGenerator(FabricDataGenerator generator) {
+        var pack = generator.createPack();
+        pack.addProvider((DataProvider.Factory<?>) TurtleDataProvider::new);
+    }
+}

projects/fabric/src/examples/resources/fabric.mod.json

@@ -0,0 +1,16 @@
+{
+    "schemaVersion": 1,
+    "id": "examplemod",
+    "version": "1.0.0",
+    "entrypoints": {
+        "main": [
+            "com.example.examplemod.FabricExampleMod"
+        ],
+        "fabric-datagen": [
+            "com.example.examplemod.FabricExampleModDataGenerator"
+        ]
+    },
+    "depends": {
+        "computercraft": "*"
+    }
+}