refine API docs

Author: turikhay

api/src/main/java/com/turikhay/mc/mapmodcompanion/Channels.java

@@ -5,14 +5,12 @@
  * modifications.
  * <p>
  * These constants can be used with the platform specific networking API to
- * register listeners or send packets. For example, registering the world id
- * channel on Fabric would look like:
+ * register listeners or send packets. For example:
  *
  * <pre>{@code
- * ClientPlayNetworking.registerGlobalReceiver(
- *         Channels.WORLDID_CHANNEL,
- *         (client, handler, buf, responseSender) -> { /* ... *\/ }
- * );
+ * registerChannel(Channels.WORLDID_CHANNEL, data -> {
+ *     // ...
+ * });
  * }</pre>
  */
 public interface Channels {

api/src/main/java/com/turikhay/mc/mapmodcompanion/Id.java

@@ -8,7 +8,12 @@
  */
 public interface Id {
 
-    /** Magic value used in some packet formats. */
+    /**
+     * Flag value used by VoxelMap-style packets.
+     * <p>
+     * When present at the start of a packet, the value {@code 42} signals that
+     * the payload follows the VoxelMap format.
+     */
     int MAGIC_MARKER = 42;
 
     /**
@@ -42,6 +47,13 @@ default <IdType> IdType withId(int id) {
 
     /**
      * Converts raw packet bytes into an {@link Id} instance.
+     * <p>
+     * Implementations are typically stateless and expose a shared
+     * {@code instance()} method so they can be reused:
+     *
+     * <pre>{@code
+     * PrefixedId id = PrefixedId.Deserializer.instance().deserialize(data);
+     * }</pre>
      *
      * @param <IdType> type of id produced
      */
@@ -58,6 +70,13 @@ interface Deserializer<IdType extends Id> {
 
     /**
      * Produces raw packet bytes from an {@link Id} instance.
+     * <p>
+     * Like deserializers, serializers commonly provide a shared
+     * {@code instance()} for reuse:
+     *
+     * <pre>{@code
+     * byte[] data = PrefixedId.Serializer.instance().serialize(id);
+     * }</pre>
      *
      * @param <IdType> type of id to serialize
      */

api/src/main/java/com/turikhay/mc/mapmodcompanion/LevelMapProperties.java

@@ -9,6 +9,10 @@ public interface LevelMapProperties {
 
     /**
      * Deserializes standard id packets.
+     *
+     * <pre>{@code
+     * StandardId id = LevelMapProperties.Deserializer.instance().deserialize(data);
+     * }</pre>
      */
     class Deserializer implements Id.Deserializer<StandardId> {
         private static Deserializer INSTANCE;
@@ -38,6 +42,10 @@ public static Deserializer instance() {
 
     /**
      * Serializes standard ids into packet byte arrays.
+     *
+     * <pre>{@code
+     * byte[] data = LevelMapProperties.Serializer.instance().serialize(id);
+     * }</pre>
      */
     class Serializer implements Id.Serializer<StandardId> {
         private static Serializer INSTANCE;

api/src/main/java/com/turikhay/mc/mapmodcompanion/PrefixedId.java

@@ -6,6 +6,8 @@
 
 /**
  * Identifier encoded with a zero-prefixed length and optional magic marker.
+ * When present, the marker has the value {@link Id#MAGIC_MARKER} (42) which
+ * flags a VoxelMap-style packet.
  * <p>
  * The format matches the one used by Xaero's minimap when responding to world
  * id requests. The {@link Deserializer} and {@link Serializer} nested classes
@@ -144,6 +146,10 @@ public static Deserializer instance() {
 
     /**
      * Serializes {@link PrefixedId} instances into packet byte arrays.
+     *
+     * <pre>{@code
+     * byte[] data = PrefixedId.Serializer.instance().serialize(id);
+     * }</pre>
      */
     public static class Serializer implements Id.Serializer<PrefixedId> {
         private static Serializer INSTANCE;
@@ -157,7 +163,7 @@ public byte[] serialize(PrefixedId id) {
                     out.writeByte(0);      // packetId, or prefix
                 }
                 if (id.usesMagicByte) {
-                    out.writeByte(MAGIC_MARKER); // 42 (literally)
+                    out.writeByte(MAGIC_MARKER); // VoxelMap-style flag (42)
                 }
                 byte[] data = String.valueOf(id.getId()).getBytes(StandardCharsets.UTF_8);
                 out.write(data.length);      // length