Clarify docs around registering peripherals

projects/common-api/build.gradle.kts

@@ -8,6 +8,8 @@ plugins {
     id("cc-tweaked.vanilla")
 }
 
+val mcVersion: String by extra
+
 java {
     withJavadocJar()
 }
@@ -17,8 +19,36 @@ dependencies {
 }
 
 tasks.javadoc {
+    title = "CC: Tweaked $version Minecraft $mcVersion"
     include("dan200/computercraft/api/**/*.java")
 
+    options {
+        (this as StandardJavadocDocletOptions)
+
+        groups = mapOf(
+            "Common" to listOf(
+                "dan200.computercraft.api",
+                "dan200.computercraft.api.lua",
+                "dan200.computercraft.api.peripheral",
+            ),
+            "Upgrades" to listOf(
+                "dan200.computercraft.api.client.turtle",
+                "dan200.computercraft.api.pocket",
+                "dan200.computercraft.api.turtle",
+                "dan200.computercraft.api.upgrades",
+            ),
+        )
+
+        addBooleanOption("-allow-script-in-comments", true)
+        bottom(
+            """
+            <script src="https://cdn.jsdelivr.net/npm/[email protected]/components/prism-core.min.js"></script>
+            <script src="https://cdn.jsdelivr.net/npm/[email protected]/plugins/autoloader/prism-autoloader.min.js"></script>
+            <link href=" https://cdn.jsdelivr.net/npm/[email protected]/themes/prism.min.css " rel="stylesheet">
+            """.trimIndent(),
+        )
+    }
+
     // Include the core-api in our javadoc export. This is wrong, but it means we can export a single javadoc dump.
     source(project(":core-api").sourceSets.main.map { it.allJava })
 }

projects/common-api/src/main/java/dan200/computercraft/api/network/wired/WiredElement.java

@@ -14,7 +14,7 @@
  * as a proxy for all network objects. Whilst the node may change networks, an element's node should remain constant
  * for its lifespan.
  * <p>
- * Elements are generally tied to a block or tile entity in world. In such as case, one should provide the
+ * Elements are generally tied to a block or block entity in world. In such as case, one should provide the
  * {@link WiredElement} capability for the appropriate sides.
  */
 public interface WiredElement extends WiredSender {

projects/common/src/main/java/dan200/computercraft/shared/computer/apis/CommandAPI.java

@@ -248,7 +248,7 @@ public final Object[] getBlockPosition() {
      * Get some basic information about a block.
      * <p>
      * The returned table contains the current name, metadata and block state (as
-     * with [`turtle.inspect`]). If there is a tile entity for that block, its NBT
+     * with [`turtle.inspect`]). If there is a block entity for that block, its NBT
      * will also be returned.
      *
      * @param x         The x position of the block to query.

projects/common/src/main/java/dan200/computercraft/shared/data/HasComputerIdLootCondition.java

@@ -15,7 +15,7 @@
 import java.util.Set;
 
 /**
- * A loot condition which checks if the tile entity has a non-0 ID.
+ * A loot condition which checks if the block entity has a computer ID.
  */
 public final class HasComputerIdLootCondition implements LootItemCondition {
     public static final HasComputerIdLootCondition INSTANCE = new HasComputerIdLootCondition();

projects/core-api/src/main/java/dan200/computercraft/api/lua/GenericSource.java

@@ -23,7 +23,7 @@
  *
  * <pre>{@code
  * public class InventoryMethods implements GenericSource {
- *     \@LuaFunction( mainThread = true )
+ *     \@LuaFunction(mainThread = true)
  *     public int size(IItemHandler inventory) {
  *         return inventory.getSlots();
  *     }

projects/core-api/src/main/java/dan200/computercraft/api/package-info.java

@@ -7,11 +7,13 @@
  * <p>
  * You probably want to start in the following places:
  * <ul>
- *     <li>{@link dan200.computercraft.api.peripheral.IPeripheral} for registering new peripherals.</li>
+ *     <li>{@link dan200.computercraft.api.peripheral} for 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>{@link dan200.computercraft.api.turtle.ITurtleUpgrade} for turtle upgrades.</li>
+ *     <li>{@link dan200.computercraft.api.pocket.IPocketUpgrade} for pocket upgrades.</li>
  * </ul>
  */
 @DefaultQualifier(value = NonNull.class, locations = {

projects/core-api/src/main/java/dan200/computercraft/api/peripheral/GenericPeripheral.java

@@ -19,17 +19,17 @@ public interface GenericPeripheral extends GenericSource {
      * Unlike normal {@link IPeripheral}s, {@link GenericPeripheral} do not have to have a type. By default, the
      * resulting peripheral uses the resource name of the wrapped block entity (for instance {@code minecraft:chest}).
      * <p>
-     * However, in some cases it may be more appropriate to specify a more readable name. Overriding this method allows
-     * you to do so.
+     * However, in some cases it may be more appropriate to specify a more readable name, or provide
+     * {@linkplain PeripheralType#getAdditionalTypes() additional types}. Overriding this method allows you to do so.
      * <p>
-     * When multiple {@link GenericPeripheral}s return a non-empty peripheral type for a single tile entity, the
-     * lexicographically smallest will be chosen. In order to avoid this conflict, this method should only be
-     * implemented when your peripheral targets a single tile entity <strong>AND</strong> it's likely that you're the
-     * only mod to do so. Similarly this should <strong>NOT</strong> be implemented when your methods target a
-     * capability or other interface (such as Forge's {@code IItemHandler}).
+     * When multiple {@link GenericPeripheral}s provide a {@linkplain PeripheralType#getPrimaryType() primary peripheral
+     * type} for a single block entity, the lexicographically smallest will be chosen. In order to avoid this conflict,
+     * primary types should only be used when your peripheral targets a single block entity <strong>AND</strong> it's
+     * likely that you're the only mod to do so.
      *
      * @return The type of this peripheral or {@link PeripheralType#untyped()}.
      * @see IPeripheral#getType()
+     * @see IPeripheral#getAdditionalTypes()
      */
     default PeripheralType getType() {
         return PeripheralType.untyped();

projects/core-api/src/main/java/dan200/computercraft/api/peripheral/IDynamicPeripheral.java

@@ -10,7 +10,6 @@
  * A peripheral whose methods are not known at runtime.
  * <p>
  * This behaves similarly to {@link IDynamicLuaObject}, though also accepting the current {@link IComputerAccess}.
- * Generally one may use {@link LuaFunction} instead of implementing this interface.
  */
 public interface IDynamicPeripheral extends IPeripheral {
     /**

projects/core-api/src/main/java/dan200/computercraft/api/peripheral/IPeripheral.java

@@ -4,26 +4,36 @@
 
 package dan200.computercraft.api.peripheral;
 
+import dan200.computercraft.api.lua.ILuaContext;
 import dan200.computercraft.api.lua.LuaFunction;
+import dan200.computercraft.api.lua.LuaTask;
 
 import javax.annotation.Nullable;
 import java.util.Set;
 
 /**
- * The interface that defines a peripheral.
+ * A peripheral is an external device that a computer can interact with.
  * <p>
- * In order to expose a peripheral for your block or block entity, you should either attach a capability (Forge) or
- * use the block lookup API (Fabric). This interface <em>cannot</em> be implemented directly on the block entity.
+ * Peripherals can be supplied by both a block (or block entity), or from
+ * {@linkplain dan200.computercraft.api.turtle.ITurtleUpgrade#createPeripheral(dan200.computercraft.api.turtle.ITurtleAccess, dan200.computercraft.api.turtle.TurtleSide) turtle}
+ * or {@linkplain dan200.computercraft.api.pocket.IPocketUpgrade#createPeripheral(dan200.computercraft.api.pocket.IPocketAccess) pocket}
+ * upgrades.
  * <p>
- * Peripherals should provide a series of methods to the user, either using {@link LuaFunction} or by implementing
- * {@link IDynamicPeripheral}.
+ * See the {@linkplain dan200.computercraft.api.peripheral package documentation} for more information on registering peripherals.
+ * <p>
+ * Peripherals should provide a series of methods to the user, typically by annotating Java methods with
+ * {@link LuaFunction}. Alternatively, {@link IDynamicPeripheral} may be used to provide a dynamic set of methods.
+ * Remember that peripheral methods are called on the <em>computer</em> thread, and so it is not safe to interact with
+ * the Minecraft world by default. One should use {@link LuaFunction#mainThread()} or
+ * {@link ILuaContext#executeMainThreadTask(LuaTask)} to run code on the main server thread.
  */
 public interface IPeripheral {
     /**
      * Should return a string that uniquely identifies this type of peripheral.
      * This can be queried from lua by calling {@code peripheral.getType()}
      *
      * @return A string identifying the type of peripheral.
+     * @see PeripheralType#getPrimaryType()
      */
     String getType();
 
@@ -81,7 +91,7 @@ default void detach(IComputerAccess computer) {
     }
 
     /**
-     * Get the object that this peripheral provides methods for. This will generally be the tile entity
+     * Get the object that this peripheral provides methods for. This will generally be the block entity
      * or block, but may be an inventory, entity, etc...
      *
      * @return The object this peripheral targets
@@ -95,7 +105,7 @@ default Object getTarget() {
      * Determine whether this peripheral is equivalent to another one.
      * <p>
      * The minimal example should at least check whether they are the same object. However, you may wish to check if
-     * they point to the same block or tile entity.
+     * they point to the same block or block entity.
      *
      * @param other The peripheral to compare against. This may be {@code null}.
      * @return Whether these peripherals are equivalent.

projects/core-api/src/main/java/dan200/computercraft/api/peripheral/PeripheralType.java

@@ -96,6 +96,7 @@ public static PeripheralType ofAdditional(String... additionalTypes) {
      * Get the name of this peripheral type. This may be {@code null}.
      *
      * @return The type of this peripheral.
+     * @see IPeripheral#getType()
      */
     @Nullable
     public String getPrimaryType() {
@@ -107,6 +108,7 @@ public String getPrimaryType() {
      * a peripheral might have.
      *
      * @return All additional types.
+     * @see IPeripheral#getAdditionalTypes()
      */
     public Set<String> getAdditionalTypes() {
         return additionalTypes;

projects/core-api/src/main/java/dan200/computercraft/api/peripheral/WorkMonitor.java

@@ -11,7 +11,7 @@
  * Monitors "work" associated with a computer, keeping track of how much a computer has done, and ensuring every
  * computer receives a fair share of any processing time.
  * <p>
- * This is primarily intended for work done by peripherals on the main thread (such as on a tile entity's tick), but
+ * This is primarily intended for work done by peripherals on the main thread (such as on a block entity's tick), but
  * could be used for other purposes (such as complex computations done on another thread).
  * <p>
  * Before running a task, one should call {@link #canWork()} to determine if the computer is currently allowed to